Okta

Use Okta as an OpenID Connect (OIDC) identity provider (IdP) for the apps in your cluster. Then, configure the Gloo Gateway external auth server with the OIDC details. You can adapt these steps for other IdPs.

Before you begin link

1. Follow the Get started guide to install Gloo Gateway, set up a gateway resource, and deploy the httpbin sample app.

2. Get the external address of the gateway and save it in an environment variable.

     export INGRESS_GW_ADDRESS=$(kubectl get svc -n gloo-system gloo-proxy-http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS  
     

     kubectl port-forward deployment/gloo-proxy-http -n gloo-system 8080:8080
     

Step 1: Set up an Okta OIDC app link

Configure an Okta OIDC app to get the information that you need to create external auth policies to secure your resources.

1. Open the Okta dashboard. If you don’t have an Okta account that you can use, sign up for an Okta developer account.

2. From the Applications menu, click Applications > Create New App. Note that you might see a Create App Integration button instead.

   

   

3. Select OIDC - OpenID Connect as the sign-in method for your app and Single-Page Application as your application type. Then, click Next.

4. Enter a name for your app and optionally upload a logo.

5. For Grant type, check both Authorization Code and Refresh Token.

6. For Sign-in redirect URIs, enter the location from which you want to allow users to log in. The URL is composed of hostname that you set up for your Portal resources and the /callback path. For example, for the developer portal frontend app, you might enter:

   • https://developer.example.com to let a user log in from the secured home page.
   • React starter app: https://developer.example.com/apis to let a user log in from the APIs page.
   • Backstage frontend plug-in: https://developer.example.com/gloo-platform-portal to let a user log in from the Gloo Portal Backstage plug-in page.
   • https://developer.example.com/callback for the callback path.

7. For the Sign-out redirect URIs, enter the location to redirect the user after logging out, such as the following examples:

   • React starter app: https://developer.example.com/logout.
   • Backstage frontend plug-in: https://developer.example.com/gloo-platform-portal/logout

8. From the Assignments section, select Allow everyone in your organization to access. This way, you do not need to assign a user or group to this app. Instead, you can use your Okta developer account credentials to test the Okta authentication flow.

9. Click Save to save your changes. You are redirected to the Okta app details page.

10. From the General tab on the Okta app details page, note the Client ID.

    

    

11. Store the Client ID as an environment variable.

      export CLIENT_ID=<client-id>
      

Step 2: Configure other Okta account details link

Configure other Okta account details, such as the claims that you want to include in the access token.

1. From the navigation menu, click Security > API.

2. Click the Authorization Server that you want to use, such as default.

3. From the Settings tab, click the Metadata URI. In a new tab, your browser opens to a URL similar to https://dev-1234567.okta.com/oauth2/default/.well-known/oauth-authorization-server.

4. From the metadata URI, search for and save the endpoints that you need as environment variables.

   1. The token_endpoint is where to get the OAuth token.

        export TOKEN_ENDPOINT=https://dev-1234567.okta.com/oauth2/default/v1/token
        

   2. The authorization_endpoint is where to get the PKCE authorization code.

        export AUTH_ENDPOINT=https://dev-1234567.okta.com/oauth2/default/v1/authorize
        

   3. The end_session_endpoint is where to end the session.

        export LOGOUT_ENDPOINT=https://dev-1234567.okta.com/oauth2/default/v1/logout
        

5. Get the JSON Web Key Set (JWKS) that you use later for an inline access token external auth policy.

   1. From the metadata URI, find the jwks_uri endpoint. In a new tab, open this endpoint, such as https://dev-1234567.okta.com/oauth2/default/v1/keys.

        export OKTA_JWKS_URI=<jwks_uri>
        

   2. Copy and save the entire value of these keys as an environment variable.

        export CERT_KEYS={"keys":[{"kty":"RSA","alg":"RS256","kid":"sKv...","use":"sig","e":"AQAB","n":"kdhR..."}]}
        

6. Return to the authorization server page in Okta.

7. From the Claims tab, click Add Claim to add any claims that you want the access token to include. Later, you can use these claims in your portal groups. For example, the portal group might require a member of organization: solo.io to access certain API products. For more information about claims, see JWT structure. For example, you might configure the following claims:

   • email: Return the user’s email as configured in the user’s profile.
   • organization: Return the user’s organization as configured in the user’s profile.
   • group: Include any group (match regex *) for the openid scope.

   

   

8. From the Token Preview tab, verify that the tokens return the information that you expect, such as the same kid as $CERT_KEYS value that you previously saved and the claims that you configured.

   1. In OAuth/OIDC client, enter the name of your app.
   2. In Grant type, select Authorization Code.
   3. In User, enter your username or the name of the user that you want to log in to the frontend developer portal.
   4. In Scopes, enter openid.
   5. Click Preview Token, then flip between the id_token and token previews.
   6. If you do not see the claim information that you expect, click your profile > My settings and review your personal information. For example, you might not have an organization or group set. You can edit your profile to include this information, then preview the token again.

   

   

Step 3: Add custom claims link

Optionally, you can add custom claims to the ID tokens that Okta generates for a user. For example, you might want to create policies that grant access based on custom claims. If you use Gloo Portal, you can use custom claims to authorize users to ApiProducts by creating a PortalGroup.

Gloo Portal includes a sample React frontend app for a developer portal. To protect the frontend app with an OAuth login, the OIDC provider must return access and ID tokens with the following claims. Keep in mind that your OIDC provider might also require the users to have values for these claims in order to return the claim (such as a first and last name, not just a username, configured in the user profile).

Claims required to log in:

• email
• name
• preferred_username
• sub

Claims required for admin tasks such as managing subscriptions:

• group: admin, note that this claim cannot be returned as an array.

Some OIDC providers do not return all of these claims by default. In the AuthConfig, you might be able to request additional scopes, such as openid, profile, and email to get back tokens with these claims. Otherwise, create custom claims and claim mapping for these tokens in your OIDC provider.

In Okta, you must request the openid, email, and profile scopes to get back the required claims to login. For the group: admin claim, group is a reserved claim. You must set this value to admin for the admin users.

The following steps create a group called Users and assign user1@example.com to the group. The group membership is mapped to a X-groups claim in the ID token. For more information, see the Okta docs.

1. If you are not already, log in to the Okta dashboard.

2. Create the Users group.

   1. From the menu, click Directory > Groups.
   2. Click Add group.
   3. Enter the name Users, then click Save.
   4. In the list of groups, click Users.
   5. From the People tab, click Assign people.
   6. From the list of people, click the plus + button to assign the person to the Users group. Then, click Done.
   7. From the Applications tab, click Assign applications.
   8. Find the application that you use, click Assign, and then click Done.

3. Configure the custom X-groups claim.

   1. From the menu, click Security > API.

   2. From the Authorization Servers tab, find the server that your app uses, such as default.

   3. From the Claims tab, click Add Claim.

   4. Fill in the details for the group claim.

      • Name: Enter the name for the claim, such as X-groups.
      • Include in token type: Select ID Token and Always.
      • Value type: Select Groups.
      • Filter: Select Matches regex, and then enter .* to match any group.
      • Include in: Select Any scope.
      • Click Create.

4. From the Token Preview tab, verify that the claim is included in the user’s ID token.

   • OAuth/OIDC client: Select your app.
   • Grant type: Select Authorization Code.
   • User: Select your user, such as user1@example.com.
   • Scopes: Enter openid, profile, email, and groups. Note that for Gloo Portal, you must include these scopes in the AuthConfig policy that you create later.
   • Click Preview Token.

5. Verify that the Payload contains the required email, name, preferred_username, sub, and groups claims, along with the X-groups custom claim.

     {
     "sub": "1234...",
     "name": "user1",
     "email": "user1@example.com",
     "ver": 1,
     "iss": "https://<domain>.okta.com/oauth2/default",
     "aud": "1234...",
     "iat": 1732217445,
     "exp": 1732221045,
     "jti": "ID.1234...",
     "amr": [
       "pwd"
     ],
     "idp": "1234...",
     "nonce": "nonce",
     "auth_time": 1000,
     "at_hash": "preview_at_hash",
     "X-groups": [
       "Everyone",
       "Users"
     ]
   }
     

Step 4: Create an OAuth policy link

Create the resources needed to enforce an OAuth policy that uses Okta as the OIDC provider.

1. Create an AuthConfig resource with your external authentication rules. The following example sets up access token validation. To validate access tokens, you configure the Gloo Gateway external auth server to use the Okta JWKS server at the address that you previously got when you configured Okta. For more options, see the OAuth2 API docs.

     kubectl apply -f - <<EOF
   apiVersion: enterprise.gloo.solo.io/v1
   kind: AuthConfig
   metadata:
     name: oauth-okta
     namespace: httpbin
   spec:
     configs:
       - oauth2:
           accessTokenValidation:
             jwt:
               remoteJwks:
                 url: "${OKTA_JWKS_URI}"
   EOF
     

2. Create a RouteOption resource that refers to the AuthConfig resource that you just created.

     kubectl apply -f- <<EOF
   apiVersion: gateway.solo.io/v1
   kind: RouteOption
   metadata:
     name: httpbin-oauth
     namespace: httpbin
   spec:
     options:
       extauth:
         configRef:
           name: oauth-okta
           namespace: httpbin
   EOF
     

3. Create an HTTPRoute resource for the httpbin app that requires authentication with Okta for requests along the /status/200 path. If the request does not include a valid token, the request is denied with a 403 Forbidden HTTP status code.

     kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: httpbin-oauth-okta
     namespace: httpbin
   spec:
     hostnames:
     - "www.httpbin.org"
     parentRefs:
     - name: http
       namespace: gloo-system
     rules:
       - matches:
         - path:
             type: Exact
             value: /status/200
         filters:
           - type: ExtensionRef
             extensionRef:
               group: gateway.solo.io
               kind: RouteOption
               name: httpbin-oauth
         backendRefs:
           - name: httpbin
             port: 8000
   EOF
     

Step 5: Verify the OAuth policy link

1. Verify that your resources are in an Accepted state. If not, review the messages. Common issues include referencing the wrong RouteOption resource in the extensionRef filter, creating multiple RouteOption resources and attaching them via the targetRefs option, or missing ReferenceGrants for resources that are in different namespaces.

     kubectl describe AuthConfig -n httpbin oauth-okta
   kubectl describe RouteOption -n httpbin httpbin-oauth
   kubectl describe HttpRoute -n httpbin httpbin-oauth-okta
     

2. Send a request to the protected httpbin route. Verify that you get back a 403 error status code.

     curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.httpbin.org:8080"
     

   Example output:

     HTTP/1.1 403 Forbidden
     

3. Get an access token for an authorized user of your Okta app. For more information, see the Okta refresh token docs or the Okta developer forum about Using Postman to get an access token.

     export ACCESS_TOKEN=<access_token>
     

4. Repeat the request to your httpbin app. This time, include the access token that you just created as part of the authorization header. Verify that you get back a 200 success status code.

     curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.httpbin.org:8080" -H "Authorization: Bearer $ACCESS_TOKEN"
     

   Example output:

     HTTP/1.1 200 OK
     

Cleanup link

You can optionally remove the resources that you set up as part of this guide.

1. Delete the resources that you created for the external auth policy.

     kubectl delete AuthConfig -n httpbin oauth-okta
   kubectl delete RouteOption -n httpbin httpbin-oauth
   kubectl delete HttpRoute -n httpbin httpbin-oauth-okta
     

2. Remove your Okta OIDC app.

   1. Open the Okta dashboard and select Applications > Applications from the menu.
   2. Find your Okta OIDC app.
   3. Click the gear icon and from the drop-down menu, select Deactivate.