Configuring Single Sign-On for Sample Application

In this guide, you’ll learn how to configure Okta identity provider to use with the sample application Animal Rescue.

Configuring Okta OIDC provider

Login to Okta admin dashboard. You can use a free developer account or configure your existing account.

Create authorization server for Animal Rescue

New authorization server is required because Animal Rescue will need it’s own set of scopes and claims.

Okta provides two types of management API, “Classic UI” and “Developer Console”. This guide is using “Developer Console” however all configuration are available in Classic UI as well.

  1. Go to API -> Authorization Servers and click “Add Authorization Server”.
  2. Use “Animal Rescue” name and set audience api://animal-rescue.
  3. Now go to new created settings page, copy the value in “Issuer” field. This should be used as issuer-uri during Gateway setup.
  4. Switch to “Scopes” tab and add a new scope: animals.adopt (with any display name and description), set “User Consent” and “Metadata Publish” to Yes.
  5. Switch to “Claims” tab and add a new claim: groups, set “Include in token type” to always include to ID Token, value type to “Groups” with filter matching regex “.*” (so all groups are included). Optionally, configure “Include in” to groups scope (you need to create the scope first) if you’d like to include groups information only when certain scope is requested and approved.
  6. Add a new claim user_name and set it to be always included into ID token, configure value to be Claim value can be configured using Okta Expression Language.
  7. Switch to “Access Policies” tab and create “Default” access policy, assigned to all clients. Add a new rule to allow authorization_code grant, for any user, any scope.

Create users and groups

Navigate to “Users -> People” from the main menu

  1. Click “Add Person” and configure all required fields.

Navigate to “Users -> Groups” from the main menu

  1. Click “Add Group” and create “Adopter” group.
  2. Click “Manage People” in “Adopter” group and add accounts you created above.

Create new application

Navigate to “Applications” in the main menu.

  1. Click “Add application”, select “Web” in the platform list, configure application name.
  2. In “Login redirect URIs” add <gateway url>/login/oauth2/code/sso.
  3. Enable “Authorization Code” grant type for the app.
  4. In “Assignments” section, assign your test users to the app.
  5. Copy “Client ID” and “Client Secret”.

Configuration summary

After you completed the steps above, you should have the following values: - Issuer URI. That should be value from the authorization server you created, not your account Okta domain. - Client ID - Client secret - One or two test users ideally with different groups for testing

Make sure you have them before proceeding to the next step.

Configure Animal Rescue app

Clone the repo first.

Configure SSO params

  1. Edit k8s/base/sso-credentials-for-backend.txt jwk-set-uri=<issuer uri>/v1/keys
  2. Edit k8s/overlays/sso-secret-for-gateway/secrets/test-sso-credentials.txt scope=openid,profile,email,groups,animals.adopt client-id=<client id> client-secret=<client id> issuer-uri=<issuer uri>

If you decided to use groups scope to get groups information, make sure it is listed in scope parameter.

Issuer URI must exactly match value from the server configuration, including trailing slashes! You can always check expected value by navigating to <issuer-uri>/.well-known/openid-configuration URL.

  1. Edit k8s/base/animal-rescue-backend-route-config.yaml and add roles-attribute-name into sso section: sso: secret: animal-rescue-sso roles-attribute-name: "groups"

The default value is “roles” you alternatively you can configure Okta to return “roles” claim instead of “groups”.

Configure routes security

  1. Edit k8s/base/animal-rescue-backend-route-config.yaml file. Add Scopes=animals.adopt filter to /api/animals/*/adoption-requests/** route if you’d like to use scopes to authorize access to Adoption Request API, or Roles=Adopter if you’d like to use roles. You can keep both filters as well.

Deploy the app

Run kustomize build ./k8s | kubectl apply -f - or refer to Animal Rescue README for most up to date deployment instructions.


Navigate to your gateway URL.

If you are using dynamic IP address you may need to go back to Okta and configure this IP address in the list of allowed Redirect URIs.

Try logging in with different test users, within or without “Adopter” groups and add, edit or delete adoption request. You should see successfull response or “Request failed with status code 403” error message depending on your groups list and approved scopes.