Gloo Portal is available as an element of the Gloo Edge Enterprise subscription.  But since not all customers use it, it is packaged as a separate installation from the core Edge API Gateway.  We are using Portal v1.1.1 for this exercise.  Follow this guide to install Portal with Gloo Edge as its deployment target.

Note that Gloo Portal also supports deployment to Istio ingress gateways in addition to Gloo Edge.  However, in this blog post we’ll focus strictly on deployment to Gloo Edge.

% kubectl apply -n default -f \
  https://raw.githubusercontent.com/solo-io/gloo/v1.9.0/example/petstore/petstore.yaml
% kubectl -n default rollout status deployment petstore
deployment "petstore" successfully rolled out

kubectl apply -f \
  https://raw.githubusercontent.com/jameshbarton/solo-resources/main/portal-self-reg/0-apidoc-prod-envt-portal.yaml

cat <<EOF | sudo tee -a /etc/hosts

# Added for the Solo.io Gloo Portal Guides
${INGRESS_HOST} api.example.com
${INGRESS_HOST} petstore.example.com
EOF

% curl http://api.example.com/api/pets
[{"id":1,"name":"Dog","status":"available"},{"id":2,"name":"Cat","status":"pending"}]

Configure Okta for Self-Registration

Establish Okta Account

Establish Okta Application

Configure an Okta User Group (and maybe some Users)

When you establish an Okta application, you get one user group for free, the Everyone group.  We could use that default group to drive this exercise.  But instead let’s make this a bit more realistic by creating a separate group to hold our set of users (including self-registered ones) that will have access to our “public” Petstore API.  Let’s establish a group called PetstoreUsers.  Navigate to Directory > Groups and establish the PetStoreUsers group.

You may also want to create some Okta Users and assign them to the PetstoreUsers Group, although that isn’t strictly required since soon we’ll be able to create Users dynamically from our web interface using self-service registration.

Configure a Groups Claim from the Petstore Application

Gloo Portal expects there to be a claim presented from the IdP as part of an ID token in the OIDC auth flow that identifies the Groups that a particular authorized user is part of.  More information on how this works in Okta is presented here.  Okta does not present this claim by default.

So we need to enable this by specifying a custom groups claim in two different places, the Okta Application configuration and the Authorization Server configuration.

First, let’s tackle the Application configuration.  Navigate to Applications > Applications in the admin console and click through to the Petstore application.  Switch to the Sign On tab and edit the Groups claim filter to specify the claim name is groups and that it should match the regex pattern .*.  In other words, all group names that are part of the application will be passed back to the Portal in the groups claim.

Second, we’ll configure the Authorization Server to pass back the groups claim with just the PetstoreUsers group name.  Navigate in the admin console to Security > API and click through to the default Authorization Server config.  Switch to the Claims tab and add a groups claim as shown below.

Note that we specified the name of the claim as groups, we changed the token type value from the default to ID Token, and we specified a Filter value to only include groups whose names start with the string Petstore, which will match our group named PetstoreUsers.

Enable Okta Self-Registration on Account

By default, Okta accounts are not enabled for self-service registration (SSR).  In this section, we will walk through the steps to configure this.  For more details, the Okta guide to managing self-registration settings is quite helpful.

First, we will navigate the Okta admin console to Directory > Self-Service Registration and enable the feature.

After enabling SSR, we need to customize the settings for our application.  We specify the Assign to group as PetstoreUsers, the user group we created earlier in this exercise, so that any users created by SSR will automatically be placed into the group that we will configure to have access to the Petstore APIs.

And just to save a bit of time for this exercise, we will also turn off the default setting that the user must verify their email address in order to be activated as a member of the group.  Okta will still send a confirmation email to the specified address, but it will not require any action from the newly registered user in response.

Enable Okta Self-Registration on Petstore Application

Not only is self-registration disabled by default on Okta accounts, it is also disabled by default on the Applications that comprise those accounts.  In this section, we will walk through the process of enabling and configuring SSR on the Okta Petstore Application.

First, use the Okta admin console to navigate back to the Petstore Application and switch to the Assignments tab.  You should notice that the SELF SERVICE panel is marked Disabled.  Edit those settings to allow users to request access to the application, and to mark administrator approval as Not Required.

Also on the Assignments tab, select Groups and assign the PetstoreUsers group that we created earlier to this application.  Your final Assignments tab interface should look something like below.

Integrate Petstore Portal with Okta

In this section, we’ll walk through the steps for configuring OIDC integration with Okta, which will allow us to delegate auth decisions to the IdP.

Establish Okta Client Secret

The OIDC standard specifies two bits of credentials that an OIDC client needs to present to its provider, a client ID and a client secret.  Okta provides this information on its admin console’s Application detail interface.

We will use the client secret from Okta to configure a corresponding Kubernetes Secret, which we will apply to our Portal config as part of the OIDC integration.

export CLIENT_SECRET=your-oidc-client-secret-here
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: petstore-portaloidc-secret
  namespace: default
data:
  client_secret: "$(echo $CLIENT_SECRET | base64)"
EOF

Our initial Portal had no authorization configured at all.  There is an internal HTTP basic auth mechanism that we could use, but that is typically used just for testing purposes.  The internal mechanism is missing self-registration and a host of other features found in enterprise IdP’s like Okta.

We will now add to our Portal configuration an oidcAuth stanza to connect with our Okta application. You’ll need to fill in the client ID shown in Okta and the correct host for your developer account in the issuer URL. Ensure that you include the groups value in the additionalScopes field so that the group claims are included in the request.

cat <<EOF | kubectl apply -f -
apiVersion: portal.gloo.solo.io/v1beta1
kind: Portal
metadata:
  name: petstore-portal
  namespace: default
spec:
  banner:
    fetchUrl: https://i.imgur.com/EXbBN1a.jpg
  customStyling: {}
  description: The Gloo Portal for the Petstore API
  displayName: Petstore Portal
  domains:
  - petstore.example.com
  - petstore.example.com:$INGRESS_PORT
  favicon:
    fetchUrl: https://i.imgur.com/QQwlQG3.png
  primaryLogo:
    fetchUrl: https://i.imgur.com/hjgPMNP.png
  publishedEnvironments:
  - name: dev
    namespace: default
  staticPages: []
  portalUrlPrefix: http://petstore.example.com:$INGRESS_PORT/
  oidcAuth:
    clientId: 0oaksnsdvwTd1b5wR5d6      # uses client ID from Okta application
    clientSecret:
      name: petstore-portaloidc-secret  # uses client secret from Okta application
      namespace: default
      key: client_secret
    groupClaimKey: groups  # reads the "groups" claim we configured to pass with Okta ID token
    # Issuer info available at your Okta's account .well-known OpenId config URL
    # Example: https://dev-2933640.okta.com/oauth2/default/.well-known/openid-configuration
    additionalScopes:
     - groups
    issuer: https://dev-2933640.okta.com/oauth2/default
EOF

Configure Portal Group to Shadow Okta Group

Finally, we will configure a Portal Group Custom Resource to shadow the PetstoreUsers group that we created to hold the users of our public API, including the self-registered ones.

cat <<EOF | kubectl apply -f -
apiVersion: portal.gloo.solo.io/v1beta1
kind: Group
metadata:
  name: oidc-group
  namespace: default
spec:
  accessLevel:
    apiProducts:
    - name: petstore-product  # identify APIProducts accessible to this group
      namespace: default
      environments:
      - name: dev  # identify Environments in which this APIProduct is accessible to this portal
        namespace: default
    portals:
    - name: petstore-portal   # identify Portals that will be accessible to this group
      namespace: default
  oidcGroup:
    groupName: PetstoreUsers  # identifies OIDC group that this group represents
EOF

Test Self-Registration with the Petstore Portal

Let’s see how self-registration works in practice by visiting our portal at http://petstore.example.com.

Click through the Login button and then Log in with OpenID Connect.  This redirects you to an Okta login dialog as shown below.  Note in particular the Sign up link at the bottom of the dialog, which is provided because we configured Okta for self-service registration.

Click through the Sign up link, provide the information requested, and click Register.

When everything is configured correctly, your self-registered user will be added to the PetstoreUsers group and you will be redirected back to the portal home.  But now you will notice that you are signed in to the portal with the email address of the newly registered user.

In addition to being added to the Portal, you should also receive a verification email from Okta.  Given the way that we configured SSR in Okta, this does not require confirmation by the new user.  There is a Verify Account button in the Okta-generated email, but portal use is not predicated on verification.  This message is simply a notification.  We could have configured Okta to require user confirmation but chose against it just to keep this process as simple as possible.

Play in the Portal Sandbox

Now that we are authenticated to the Petstore Portal, we can play in the portal’s execution sandbox.  Click through View APIs on the portal home page and click into the v1 sandbox.  You should see 4 operations listed there in a familiar Swagger-like style.  (The same type of interface is also presented for the newer gRPC service support as well.)

Click through the GET /api/pets operation and Try it out followed by Execute.  You should see a response from the endpoint identical to what we saw earlier in this exercise.

Congratulations!  You have now configured a customized Petstore API Portal that supports self-service registration of new users with Okta.

Learn More