Okta

​

About Okta

​

What the Okta integration enables

​

Okta Configuration

​

1. Create App Integration

• Log into your company’s Okta admin console
• Navigate to Applications > Applications
• Select Create App Integration
• Select API Services
• Title the app “Serval” (this can be any value, but make sure to give it a title that helps you remember that this application is for integration with the Serval platform.
• Hit Save & Finish creating the app integration.

​

2. Configure scopes/permissions

• Grant API scopes for the new integration. We recommend at least granting read access to users, groups and applications, as this will allow you to use read-only endpoints within Serval. However, to facilitate taking action in Okta to grant users access to applications or solve other common issues automatically, you will also need to grant some manage scopes.
• Read: okta.users.read, okta.groups.read, okta.apps.read, okta.logs.read
• Write: okta.users.manage, okta.groups.manage and okta.apps.manage
• Next, you will need to grant this app integration an admin role. Navigate to Admin roles and hit Edit Assignments.
• You must now assign roles to the application. Here is an article which explains the difference between roles and scopes. You can select one of the following options:
  • Grant Serval the Super Administrator role. This will allow Serval to access all resources in your account, but only using the API scopes you configured previously.
  • Assign another set of predefined roles. We recommend “Group Administrator” and “Application Administrator” at a minimum. Here is an article which outlines the different permissions which can be accessed with these roles.
  • Create a custom role. This option can be used if you want to configure fine grained permissions for Serval. Again, API scopes also govern which actions Serval can take in your Okta account.
• Optionally, you can create a new role.
  • If you’ve chosen to create a new role, grant it the permissions you want Serval to be able to perform.
  • Now you will need to assign a resource set to this role. Add an assignment, select the ones you like, and hit Save Changes
    
  • If you don’t already have an applicable resource set, you can create a resource set for this admin role to have control over. Navigate to Security → Administrators and then select the resources tab. Select Create a new resource set. Select the resources you want Serval to be able to manage and hit Create.
    

​

3. Complete app integration configuration:

• In general settings, uncheck the box requiring DPoP and hit Save. We do not currently provide PoP.

• Next, configure the client credentials. We use the private key/public key method for added security. Make sure your configuration looks like this:

• Next, select Add Key and then generate one. Copy the JSON **data to your clipboard and select Done.
  • Note: Just because a key was generated does not mean it was saved, the key does not save until you select Done. Please verify that a key was actually created & saved.
  

​

Serval Configuration

• In Serval, navigate to Applications and then the Available tab. Find the Okta integration and press Connect.

• Copy the JSON from the last step into the Client Secret section.
• Your Instance ID should be the domain of your okta instance, so if your okta is found at https://mycompany.okta.com/, your instance ID would be mycompany.okta.com . If you are in the admin console, do not include the -admin in this (i.e. mycompany-admin.okta.com)
• Your Client ID can be found at the top of the app integration page:

• Enter scopes. The scopes you enter should be a comma separated list of what you granted the application previously in Okta. For example: okta.apps.read, okta.apps.manage, okta.users.read, okta.users.manage, okta.groups.read, okta.groups.manage, okta.logs.read
• Click Save
• You should now be able to build or install workflows which leverage Okta APIs, e.g. you could build a workflow for creating a new Okta group or a new user.