You can use the OpenID Connect (OIDC) Identity Provider (IdP) to enforce OAuth policies for several important use cases, such as securing the login to your portal frontend app.

About

You can use an IdP to enforce authentication for several use cases in Gloo Portal, such as protecting APIs with external auth policies, the portal frontend app, and IdP Connect. It is recommended to use the same IdP for all your Gloo Portal use cases. The following IdPs have been successfully set up with Portal: Amazon Cognito and Keycloak. If you use another IdP, you might need to modify the steps for your setup.

Step 1: Install Keycloak

You might want to test how to restrict access to your applications to authenticated users, such as with external auth or JWT policies. You can install Keycloak in your cluster as an OpenID Connect (OIDC) provider.

The following steps install Keycloak in your cluster, and configure two user credentials as follows.

  • Username: user1, password: password, email: user1@example.com
  • Username: user2, password: password, email: user2@solo.io

Install and configure Keycloak:

  1. Create a namespace for your Keycloak deployment.

      kubectl create namespace keycloak

  2. Create the Keycloak deployment.

      kubectl -n keycloak apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/policy-demo/oidc/keycloak.yaml

  3. Wait for the Keycloak rollout to finish.

      kubectl -n keycloak rollout status deploy/keycloak

  4. Set the Keycloak endpoint details from the load balancer service.

      export ENDPOINT_KEYCLOAK=$(kubectl -n keycloak get service keycloak -o jsonpath='{.status.loadBalancer.ingress[0].ip}{.status.loadBalancer.ingress[0].hostname}'):8080
export HOST_KEYCLOAK=$(echo ${ENDPOINT_KEYCLOAK} | cut -d: -f1)
export PORT_KEYCLOAK=$(echo ${ENDPOINT_KEYCLOAK} | cut -d: -f2)
export KEYCLOAK_URL=http://${ENDPOINT_KEYCLOAK}
echo $KEYCLOAK_URL

  5. Set the Keycloak admin token. If you see a parsing error, try running the curl command by itself. You might notice that your internet provider or network rules are blocking the requests. If so, you can update your security settings or change the network so that the request can be processed.

      export KEYCLOAK_TOKEN=$(curl -d "client_id=admin-cli" -d "username=admin" -d "password=admin" -d "grant_type=password" "$KEYCLOAK_URL/realms/master/protocol/openid-connect/token" | jq -r .access_token)
echo $KEYCLOAK_TOKEN

  6. Use the admin token to configure Keycloak with the two users for testing purposes. If you get a 401 Unauthorized error, run the previous command and try again.

      # Create initial token to register the client
read -r client token <<<$(curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"expiration": 0, "count": 1}' $KEYCLOAK_URL/admin/realms/master/clients-initial-access | jq -r '[.id, .token] | @tsv')
export KEYCLOAK_CLIENT=${client}
echo $KEYCLOAK_CLIENT

# Register the client
read -r id secret <<<$(curl -k -X POST -d "{ \"clientId\": \"${KEYCLOAK_CLIENT}\" }" -H "Content-Type:application/json" -H "Authorization: bearer ${token}" ${KEYCLOAK_URL}/realms/master/clients-registrations/default| jq -r '[.id, .secret] | @tsv')
export KEYCLOAK_SECRET=${secret}
echo $KEYCLOAK_SECRET

# Add allowed redirect URIs
curl -k -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X PUT -H "Content-Type: application/json" -d '{"serviceAccountsEnabled": true, "directAccessGrantsEnabled": true, "authorizationServicesEnabled": true, "redirectUris": ["*"]}' $KEYCLOAK_URL/admin/realms/master/clients/${id}

# Add the group attribute in the JWT token returned by Keycloak
curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"name": "group", "protocol": "openid-connect", "protocolMapper": "oidc-usermodel-attribute-mapper", "config": {"claim.name": "group", "jsonType.label": "String", "user.attribute": "group", "id.token.claim": "true", "access.token.claim": "true"}}' $KEYCLOAK_URL/admin/realms/master/clients/${id}/protocol-mappers/models

# Create first user
curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"username": "user1", "email": "user1@example.com", "firstName": "Alice", "lastName": "Doe", "enabled": true, "attributes": {"group": "users"}, "credentials": [{"type": "password", "value": "password", "temporary": false}]}' $KEYCLOAK_URL/admin/realms/master/users

# Create second user
curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"username": "user2", "email": "user2@solo.io", "firstName": "Bob", "lastName": "Doe", "enabled": true, "attributes": {"group": "users"}, "credentials": [{"type": "password", "value": "password", "temporary": false}]}' $KEYCLOAK_URL/admin/realms/master/users

  7. Open the Keycloak frontend.

      open $KEYCLOAK_URL

  8. Log in to the admin console, and enter admin as the username and admin as your password.

  9. In the Keycloak admin console, go to Users, and verify that the users that created earlier are displayed. You might need to click on View all users to see them.

  10. In the Keycloak admin console, go to Clients, and verify that you can see a client ID that equals the output of $KEYCLOAK_CLIENT.

Step 2: Configure Keycloak

Configure your Keycloak client with the appropriate settings for the developer portal frontend authentication.

  1. From the Keycloak sidebar menu options, click Clients.

  2. Click the Client ID that matches the $KEYCLOAK_CLIENT that you previously set.

  3. From the client Settings tab, find the Access settings and update the following fields.

    • Valid redirect URIs field with * wildcard or the domain that you want to use for redirects.
    • Valid post logout redirect URIs field with * wildcard or the domain that you want to use for logout redirects.
    • Web origins field with * wildcard to allow all origins.

  4. Scroll down to the Capability config section and update the following sections:

    • Toggle the Client authentication setting to On.
    • Toggle the Authorization setting to On.
    • In the Authentication flow section, enable the Standard flow and Direct access grants options.

  5. At the bottom of the form, click Save. The Client successfully updated message pops up to confirm your settings are saved.

  6. Set up the client with the required manage-clients role. This way, you can use the Keycloak client to let users self-service the creation of their own OAuth credentials through the portal frontend app.

    1. From the client Service accounts roles tab, click Assign role.
    2. Find or search for the manage-clients role, check the row, and then click Assign.
    3. Verify that you see the manage-clients role in the Service accounts roles tab.

Step 3: Add custom claims

Optionally, you can add custom claims to the ID tokens that Keycloak 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. If your IdP cannot provide the group claim, such as when group is a reserved claim in Okta, you can customize this claim key name. For an example, see Customize the admin group claim name.

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 Keycloak, the name and group:admin claims are not returned by default. The following steps set up these custom claims. The steps also create a group called Users and assign user1 to this group, but not user2. The group membership is mapped to an X-groups claim in the ID token. The X-groups custom claim is later used as an example for PortalGroups. For more information about claim mapping, see the Keycloak docs.

  1. If you are not already, log in to the Keycloak console as the admin user with the admin password.

      open $KEYCLOAK_URL

  2. Configure the required group claim for admins in the client.

    1. From the menu, click Manage > Clients.

    2. From the list of clients, click the client ID that you use, such as 1234567-1aa1-1a11-2bb2-cc1234567.

    3. Click the Client scopes tab, then click the assigned client scope with your client ID, such as 1234567-1aa1-1a11-2bb2-cc1234567-dedicated.

    4. Click Add mapper > By configuration.

    5. Click User Attribute.

    6. In the Name field, enter a name for the mapper, such as group-mapper.

    7. In the Token Claim Name field, enter the name for the claim in the ID token, group.

    8. Confirm that the Add to ID token setting is toggled on.

    9. Confirm that the Multivalued setting is toggled off. You must set this value so that the claim has only one value and is not an array. The Gloo Portal sample React frontend app does not accept an array for the group: admin membership.

    10. Click Save.

  3. Repeat the previous step to add the required name claim, which is not included in Keycloak tokens by default.

    1. From the Client details > Dedicated scopes > Mappers tab, click Add mapper > By configuration.

    2. Click User Property.

    3. In the Name field, enter a name for the mapper, such as name-mapper.

    4. In the Token Claim Name field, enter the name for the claim in the ID token, name.

    5. Confirm that the Add to ID token setting is toggled on.

    6. Scroll down and click Save.

  4. Configure the custom X-groups claim for the client.

    1. From the Client details > Dedicated scopes > Mappers tab, click Add mapper > By configuration.

    2. Click Group Membership.

    3. In the Name field, enter a name for the mapper, such as group-mapper.

    4. In the Token Claim Name field, enter the name for the claim in the ID token, such as X-groups.

    5. Confirm that the Add to ID token setting is toggled on.

    6. Scroll down and click Save.

  5. Create the admin and Users group.

    1. From the menu, click Manage > Groups.

    2. Click Create group.

    3. Enter the name Users, then click Create.

    4. Click Create group again, enter admin, then click Create.

    5. In the list of groups, click Users.

    6. Click the Members tab, then click Add member.

    7. Select user1, then click Add.

    8. In the list of groups, click admin.

    9. Click the Members tab, then click Add member.

    10. Select user1 and admin, then click Add.

    11. Click the Attributes tab, then click Add attribute.

    12. Enter group for the key and name for the value, and then click Save.

  6. Send a request to the Keycloak token endpoint to get back an ID token.

      curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$KEYCLOAK_CLIENT" \
  -d "client_secret=$KEYCLOAK_SECRET" \
  -d "grant_type=password" \
  -d "username=user1" \
  -d "password=password" \
  -d "scope=openid" \
  $KEYCLOAK_URL/realms/master/protocol/openid-connect/token

    Example response:

      {
  "access_token": "eyJhb...",
  "expires_in": 60,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbG...",
  "token_type": "Bearer",
  "id_token": "eyJhbG...",
  "not-before-policy": 0,
  "session_state": "8ed...",
  "scope": "openid profile email"
}

  7. To verify that the ID token includes the claims, decode the id_token claims by using a tool such as jwt.io or openssl.

      echo '<id_token>' | awk -F. '{print $2}' | base64 -d

    Example output: Notice that the required email, name, preferred_username, sub, and groups claims are returned, along with the X-groups custom claim.

      {
  "exp": 1732140757,
  "iat": 1732140697,
  "jti": "091d4648-...",
  "iss": "$KEYCLOAK_URL/realms/master",
  "aud": "72182354-...",
  "sub": "d1150127-...",
  "typ": "ID",
  "azp": "72182354-...",
  "sid": "8ed0cbaa-...",
  "at_hash": "Iww...",
  "acr": "1",
  "email_verified": false,
  "name": "Alice Doe",
  "preferred_username": "user1",
  "email": "user1@example.com",
  "group": "admin",
  "X-groups": [
    "/Users",
    "/admin"
  ]
}

Next steps

Good job! Now that your IdP is set up for use with Gloo Portal, you can use OAuth policies to secure many parts of the portal. Check out the following guides.