Setting up Okta SSO for your Oyster account

You can configure Okta to power Single Sign On (SSO) for your Oyster account. Okta SSO can be enabled for both the admins and manager roles within Oyster. This article details how you can set up Okta to work with Oyster.

What's supported 
Requirements
Important pointers before you start the set up
Step-by-step guide

What's supported in the Okta and Oyster integration 

• Single Sign-On (OpenID Connect) initiated via Okta
• Automatic account deletion in Oyster when a user is removed from an Okta application.

Requirements 

In order to proceed with setting up Okta SSO with Oyster, you must:

• Have access to an Okta and Oyster account
• Be an admin in both the Okta and Oyster account

Important pointers before you start the process 

1. You won’t be able to enable the Okta integration if at least one of the users on your company is already linked to another Okta instance, other than the one you want to enable.
2. Once the Okta integration is enabled, it can’t be turned off directly from your Oyster account, but should be done via a request raised to Oyster support.
3. Okta SSO is supported for both admin and manager roles but not supported for your team members when they log into their Oyster account. Only account admins can set up the integration. 
4. You can only “Sign in” into your existing Oyster account using this Okta SSO integration and not “Sign up”

Step-by-step guide  

Step 1 - Add the Oyster HR application in your Okta account

1. On your Okta account, go to Admin --> Applications --> Applications --> Browse App Catalog
2. Search for Oyster HR
3. Click on “Add integration”

Step 2 - Gather information from Okta
In this step, you need to gather 3 data points - Client ID, Client secret, and Okta URL

1. On the Okta admin page, click on the Oyster application and then navigate to the Sign on tab. 
2. Copy the values of Client ID and Client secret. You will use these values later in the set up process.
3. Click on OpenID Provider Metadata and search for “issuer”
4. Copy the Issuer value and add /oauth2 to the end of the URL. This URL will be later used as the “Okta URL” in your Oyster HR account. Example of an URL:Okta URL = ttps://dev-XXXXXXXX.okta.com/oauth2
   
   Note: When on the Sign On page, click Edit against Settings. Scroll down to Advanced Sign-on Settings, fill in the Client ID that you saved in Step 2.2 and click on Save.

Step 3 - Connect with Okta using your Oyster account

1. Log in to the Oyster platform.
2. Click on Integrations at the bottom of the menu bar as shown below.
   
   
   
   
3. On the Integrations page, Click on Add integrations.
4. Scroll to the Identity Providers section and click on Connect on Okta integration as shown below.
   
   
   
   
5. Click on the checkbox to confirm you have administrator permissions in Okta, then click on Connect.
6. On the next page, enter your Okta credential details. This includes your Okta ID, Okta Secret, and Okta URL. You should have this information from Step 1.
7. Click on the Submit button. The details will be submitted and a secret token will be generated and displayed as shown below.
   
   
   
8. Copy the token. 

Step 4 - Add the Okta token in your Okta account 

1. In your Okta account, go to Workflow --> Event Hooks
2. On the Event Hooks page, click on Create Event Hook
3. In the URL field, enter *https://app.oysterhr.com/api/okta/events*
4. In the Authentication field, enter the text authorization
5. In the Authentication secret field, enter your Oyster secret token
6. In the Subscribe to events section, enter the events you want Oyster to process, the following events will be required: User suspended, User deactivated, User unassigned from app. Enter these events.
7. Click on Save & Continue
8. Find the hook for revoking user access and click on it
9. Copy the token from the the “Authentication secret” text field

Note: If the name and email of a user are edited within the Okta app, this action will revoke user access into the Oyster app. For the user to re-gain access, they need to be re-invited to the Oyster app.

Okta SSO login is now enabled for your users! Your eligible users will now be able to Sign in using the SSO option on the sign-in page.