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

  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.

Step 1: Set up an Okta OIDC app

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.

    Figure: Okta application dashboard
    Figure: Okta application dashboard
  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.

    Figure: Okta General tab
    Figure: Okta General tab
  11. Store the Client ID as an environment variable.

      export CLIENT_ID=<client-id>
      

Step 2: Configure other Okta account details

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.
    Figure: Okta default auth server Claims tab
    Figure: Okta default auth server Claims tab
  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.
    Figure: Okta Token Preview tab
    Figure: Okta Token Preview tab

Step 3: Create an OAuth policy

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/v1beta1
    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 4: Verify the OAuth policy

  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

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.