On this page

Okta

Set up external auth for your apps by using the Okta OIDC provider.

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.

info

This feature is an Enterprise-only feature that requires a Gloo Gateway Enterprise license.

Before you begin

notifications

Consider increasing the default timeout of the external auth server. When you set up OAuth, the external auth server must communicate with the external OIDC provider’s authorization server. Because of this interaction, the OIDC flow might take longer than the default timeout of 200ms. In such cases, you might noticed failed requests or unexpected behavior. You can increase the default timeout by setting the requestTimeout value on the external auth settings. The external auth settings can be configured on the Gloo Gateway Settings object.

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

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

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

Open the Okta dashboard. If you don’t have an Okta account that you can use, sign up for an Okta developer account.
From the Applications menu, click Applications > Create New App. Note that you might see a Create App Integration button instead.
Figure: Okta application dashboard
Select OIDC - OpenID Connect as the sign-in method for your app and Single-Page Application as your application type. Then, click Next.
Enter a name for your app and optionally upload a logo.
For Grant type, check both Authorization Code and Refresh Token.
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.
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
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.
Click Save to save your changes. You are redirected to the Okta app details page.
From the General tab on the Okta app details page, note the Client ID.
Figure: Okta General tab
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.

From the navigation menu, click Security > API.
Click the Authorization Server that you want to use, such as default.
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.
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
  
```
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..."}]}
  
```
Return to the authorization server page in Okta.
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
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

Step 3: Create an OAuth policy

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

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
  
```

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

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

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
  
```

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

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>
  
```
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.

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

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.

Okta

Before you begin link

Step 1: Set up an Okta OIDC app link

Step 2: Configure other Okta account details link

Step 3: Create an OAuth policy link

Step 4: Verify the OAuth policy link

Cleanup link