Single sign-on with OneLogin

This guide connects OneLogin to OGDESK over OpenID Connect, which is the simpler way. If you prefer SAML, see Using SAML instead at the end.

Before you start

• In OneLogin: an administrator who can add apps and assign them to people.
• In OGDESK: the Tenant Administrator role.
• Permission to add a TXT record to your domain’s DNS.
• Your own OGDESK account on the domain you will verify, so you can test it yourself.
• Everybody who will sign in must already be a member of your OGDESK workspace. Invite them first.

Part A — Verify your email domain in OGDESK

1. 1

   Step 1: In OGDESK, go to Administration → App settings → Single sign-on.

2. 2

   Step 2: Under Email domains, type your domain and choose Claim.

   

3. 3

   Step 3: Publish the TXT record shown at your DNS provider, using the Host and Value exactly as they appear.

4. 4

   Step 4: Choose Check DNS until the domain shows Verified.

Part B — Add OGDESK in OneLogin

1. 1

   Step 1: In the OneLogin admin portal, go to Applications → Applications and choose Add App. Search for OpenId Connect and choose OpenId Connect (OIDC).

2. 2

   Step 2: Set Display Name to OGDESK and choose Save.

3. 3

   Step 3: On the Configuration tab, paste https://www.ogdesk.com/api/v1/auth/sso/callback/oidc into Redirect URI's, and choose Save.

   Copy it from Redirect / ACS URL in OGDESK if your address is different. Optionally set Login Url to your OGDESK sign-in page, so the app’s tile in the OneLogin portal opens OGDESK. A changed redirect can take up to ten minutes to apply.

4. 4

   Step 4: On the SSO tab, copy the Client ID, choose Show client secret and copy the Client Secret, and copy the Issuer URL.

   The issuer looks like https://yourcompany.onelogin.com/oidc/2. Leave Application Type as Web and Token Endpoint as Basic.

5. 5

   Step 5: Give the app to the people who need it: either open each person under Users, go to Applications and add OGDESK, or add OGDESK to a Role on the app’s Access tab and give people that role.

   OneLogin turns away anybody it has not given the app to, before they reach OGDESK.

Part C — Enter the app’s details in OGDESK

Back on the Single sign-on tab, under Identity provider:

Choose Enable single sign-on to save.

Part D — Test it, then require it

1. 1

   Step 1: Under How people sign in, tick Offer single sign-on and save.

2. 2

   Step 2: In a private browser window, open the OGDESK sign-in page, type your work email, choose Continue, then Sign in with OneLogin.

3. 3

   Step 3: On the Single sign-on tab, Last successful sign-in confirms it worked. If not, Last attempt says why. Passwords keep working while you test.

4. 4

   Step 4: Once it works, you can tick Require it, and turn passwords off. See Set up single sign-on for what that changes.

Common problems

Using SAML instead

1. 1

   Step 1: In OGDESK, save the provider with protocol SAML 2.0 first, so Redirect / ACS URL and Our entity ID appear.

2. 2

   Step 2: In OneLogin, choose Add App, search for SAML Custom Connector (Advanced), name it OGDESK, and save.

3. 3

   Step 3: On the Configuration tab, set Audience (EntityID) to OGDESK’s Our entity ID, and Recipient and ACS (Consumer) URL to OGDESK’s Redirect / ACS URL.

4. 4

   Step 4: Set ACS (Consumer) URL Validator to the same address written as a pattern: ^https:\/\/www\.ogdesk\.com\/api\/v1\/auth\/sso\/callback\/saml$

5. 5

   Step 5: Set SAML nameID format to Email, and SAML signature element to Both.

   OGDESK refuses anything that is not signed in both places.

6. 6

   Step 6: On the SSO tab, copy SAML 2.0 Endpoint (HTTP) into OGDESK’s Sign-on URL, Issuer URL into IdP entity ID, and the X.509 Certificate (under View Details) into Signing certificate.

7. 7

   Step 7: Give the app to people, as in Part B, and test it as in Part D.