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

A new authorization server is required because Animal Rescue will need it's own set of scopes and claims.

  1. Go to Security → API
  2. Under the Authorization Servers tab, click "Add Authorization Server".
  3. Use "Animal Rescue" as the name and set the audience to api://animal-rescue.
  4. Now go to new created settings page, copy the value in "Issuer" field. This should be used as issuer-uri during Gateway setup.
  5. Switch to "Scopes" tab and add a new scope: animals.adopt (with any display name and description). Check the box for "User Consent" and "Metadata" Add scope
  6. 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 a certain scope is requested and approved. Add groups claim
  7. Add a new claim user_name and set it to be always included into ID token, configure value to be The claim value can be configured using Okta Expression Language. Add username claim
  8. Switch to "Access Policies" tab and create a "Default" access policy, assigned to all clients.
  9. Add a new rule to allow authorization_code grant, for any user, any scope. Add rule

Create users and groups

Navigate to "Directory → People" from the main menu

  1. Click "Add Person" and configure all required fields.

Navigate to "Directory → Groups" from the main menu

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

Create new application

Navigate to "Applications → Applications" in the main menu.

  1. Click "Create App Integration".
  2. Select "OIDC - OpenID Connect" as the Sign-on method and select "Web Application" as the application type.
  3. In "Sign-in redirect URIs" add <gateway url>/login/oauth2/code/sso. If your gateway has not been deployed yet, you can skip this step for now and add the redirect URI later.
  4. Enable "Authorization Code" grant type for the app.
  5. In "Assignments" section, select Limit access to selected groups and add the "Adopter" group.
  6. 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 the 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

In the animal-rescue repo,

  1. Create backend/secrets/sso-credentials.txt with the following:

    jwk-set-uri=<issuer uri>/v1/keys
  2. Create gateway/sso-secret-for-gateway/secrets/test-sso-credentials.txt with the following:

    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.

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

  3. Edit gateway/gateway-demo.yaml and add roles-attribute-name into sso section:

      secret: animal-rescue-sso
      roles-attribute-name: "groups"

    The default value is "roles". Alternatively you can configure Okta to return the "roles" claim instead of "groups".

Configure routes security

Edit backend/k8s/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.

    - ssoEnabled: true
      tokenRelay: true
        - Path=/api/animals/*/adoption-requests/**
        - Method=POST,PUT,DELETE
        - "pet adoption"
        - Scopes=animals.adopt

Deploy the app

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


Port-forward the gateway demo-demo service:

kubectl port-forward service/gateway-demo 8080:80

Navigate to your gateway URL, http://localhost:8080/rescue.

Note: 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 a successful response or "Request failed with status code 403" error message depending on your groups list and approved scopes.

check-circle-line exclamation-circle-line close-line
Scroll to top icon