Use the Okta identity hub to expose a consistent OpenID Connect interface to your apps while allowing your users to use credentials that are managed by Okta to authenticate with your app.

Before you begin

  1. Set up Gloo Mesh Gateway in a single cluster.
  2. Install Bookinfo and other sample apps.

  3. Configure an HTTP listener on your gateway and set up basic routing for the sample apps.

  4. Make sure that the external auth service is installed and running. If not, install the external auth service.

      kubectl get pods -A -l app=ext-auth-service

  5. If you don’t have an Okta account, sign up for an Okta developer account.

Step 1 (optional): Prepare the Portal resources

Set up the Portal resources that you want to secure with Okta. For example, you might use Okta as the OIDC provider for the following Portal use cases:

Step 2: 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
    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
    Figure: Okta General tab
    Figure: Okta General tab

  11. Store the Client ID as an environment variable.

      export CLIENT_ID=<client-id>

Step 3: 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
    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
    Figure: Okta Token Preview tab
    Figure: Okta Token Preview tab

Step 4: Set up external auth with Okta

Set up external auth resources with Okta as the OIDC provider.

  1. Create an external auth server that enforces your extauth policy.

      kubectl apply -f - <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: ExtAuthServer
metadata:
  name: ext-auth-server
  namespace: gloo-mesh
spec:
  destinationServer:
    ref:
      cluster: $CLUSTER_NAME
      name: ext-auth-service
      namespace: gloo-mesh
    port:
      name: grpc
EOF

  2. Create an external auth policy for the oauth: "true" routes to enforce authentication via an access token from the Okta OIDC provider that you set up. Make sure to replace $CERT_KEYS with the entire {"keys":[{"kid":"_YYA...","kty":"RSA","alg":"RSA-OAEP","use":"enc","n":"r4AXlC9sR..."}]} value that you previously retrieved.

      kubectl apply -f -<<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: oauth-okta
  namespace: gloo-mesh
spec:
  applyToRoutes:
    - route:
        labels:
          oauth: "true"
  config:
    server:
      name: ext-auth-server
      namespace: gloo-mesh
      cluster: $CLUSTER_NAME
    glooAuth:
       configs:
         - oauth2:
             accessTokenValidation:
               jwt:
                 localJwks:
                  inlineString: >-
                    $CERT_KEYS
EOF

    Review the following table to understand this configuration. For more information, see the API docs.

    SettingDescription
    spec.applyToRoutesSelect the routes that you want to apply this policy to. In this example, you want to require external authentication for all routes with the oauth: "true" label.
    spec.config.serverThe external auth server to use for the policy.
    glooAuth.configs.oauth2.accessTokenValidation.jwtSet up the policy to enforce authentication via an access token that conforms to the JWT specification.
    glooAuth.configs.oauth2.accessTokenValidation.jwt.localJwksUse the local JWKS that you provide inline to validate the JWT access token.
    glooAuth.configs.oauth2.accessTokenValidation.jwt.localJwks.inlineStringProvide the JWKS keys that you retrieved from your OIDC provider inline.

  3. Verify that the external auth policy is applied successfully.

    1. Review the status of the external auth policy and make sure that it shows ACCEPTED.

        kubectl get extauthpolicy oauth-okta -n gloo-mesh -o yaml

    2. Get the authconfig resource that was created for your policy and make sure that it shows ACCEPTED.

        kubectl get authconfig -n gloo-mesh -o yaml

      If you see a REJECTED error similar to invalid character 'k' looking for beginning of object key string, try copying the $CERT_KEYS value manually again.

Step 5: Verify external auth with Okta

Try to access your app to verify that external auth is enforced by Okta.

  1. If you haven’t already, set up the frontend app for the end user-facing developer portal.

  2. In your browser, open the URL to your frontend app. Make sure that you are redirected to the Okta login screen.

      open $APP_URL

  3. Enter your Okta developer account credentials. If successfully authenticated, Okta issues an ID token and redirects you to the frontend app.

    Figure: Okta login screen
    Figure: Okta login screen
    Figure: Okta login screen
    Figure: Okta login screen

Cleanup

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

  1. Delete the external auth resources that you used for Okta.

      kubectl delete extauthserver ext-auth-server -n gloo-mesh
kubectl delete extauthpolicy oauth-okta -n gloo-mesh

  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.