Set up authorization for private APIs

To control access to private API products in your developer portal, you set up portal groups and specify the conditions that must be met to successfully authorize a user to see the private APIs. For more information about this feature, see User authorization with portal groups.

Create a portal group for authorization

To match a user with a portal group, the user must present an ID token from an OIDC provider. To learn how to integrate your developer portal with an OIDC provider, see Set up external authentication.

  1. If you have not done yet, decide on the visibility setting for the API products that are included in the developer portal. For more information, see Set API product visibility. Note that authorization is required only for private APIs. If you decide to keep your APIs public, you do not need to set up portal groups.

  2. Follow the steps to set up external authentication for your portal. This step is required to receive the ID token from your OIDC provider and identify the claims that you want to use for your portal group.

  3. Identify the claims in the ID token that you want to match on. Only if a user presents a token with the right claims, the user is matched with the portal group and is granted access to the private APIs and usage plans that you define in the portal group. The ID token is returned by the OIDC provider during authentication. Depending on the OIDC provider that you use, you can customize the claims that are being returned in the ID token. However, some OIDC provider might not allow you to create custom claims.

    If you followed the example in Set up external authentication, your ID token has a claim structure that is similar to the following:

    {
      "exp": 1681133278,
      "iat": 1681133218,
      "auth_time": 1681133218,
      "jti": "3e410301-d9a2-463f-a127-df78a94f87db",
      "iss": "http://34.xxx.xxx.xxx:8080/auth/realms/master",
      "aud": "4464fbac-ab29-4c6a-945b-14e4685c0ad4",
      "sub": "83a467a1-8f4e-4dd6-8fd1-34832ba0a84e",
      "typ": "ID",
      "azp": "4464fbac-ab29-4c6a-945b-14e4685c0ad4",
      "session_state": "aac7790f-036c-4367-b728-1f1d9dc355fe",
      "at_hash": "2nFLjyWQA2pEANc8zuhwTw",
      "acr": "1",
      "email_verified": false,
      "preferred_username": "user1",
      "email": "user1@example.com",
      "group": "users"
    }
    
  4. Create a portal group to allow access to the petstore API product for a user that presents an ID token with the group: users claim.

    kubectl apply -f- <<EOF
    apiVersion: apimanagement.gloo.solo.io/v2
    kind: PortalGroup
    metadata:
      name: petstore-group
      namespace: gloo-mesh-addons
    spec:
      name: petstore-group
      description: A group that grants access to the petstore API and allows users in this group to manage API keys for the bronze, silver, and gold usage plans.
      membership:
        - claims:
            - key: group
              value: users
      accessLevel:
        apis:
        - labels:
            api: petstore
    EOF
    
    Setting Description
    spec.membership.claims Set the claims in the JWT ID token that must be present to successfully match the user with this portal group. Note that the claims that you specify must exist in the ID token that your OIDC provider returns. You have the option to specify one or multiple claim sets. In this example, the ID token must include the group: users claim.
    spec.accessLevel.apis Select the private API products that the user can view in the developer portal after the user is matched with this portal group. To select an API product, you use a label that exists on the route table that represents the API product. To give access to all private APIs, use the same label that you set for the portal visibility, such as portal-visibility: private. For more information, see Add API products to the portal
    spec.accessLevel.usagePlans Select the usage plans that the user has access to after the user is matched with this portal group. For more information, see Add usage plans.
  5. Send a request to the /v1/apis endpoint to list the APIs that you have access to. Note that in your CLI output, only the tracks API is listed. The private petstore API is hidden because no ID token with the right claims is presented in the curl request.

    curl -vik --resolve developer.example.com:80:$INGRESS_GW_IP http://developer.example.com:80/v1/apis
    

    Example output:

    [{"apiProductDisplayName":"Catstronauts Course Tracks","apiProductId":"tracks","apiVersions":[{"apiId":"tracks-v1","apiVersion":"v1","contact":"support@example.com","customMetadata":{"compatibility":"None"},"description":"REST API for Catstronauts to retrieve data for tracks, authors and modules.","license":"License info, such as MIT","lifecycle":"Supported","termsOfService":"You must authenticate to use this API! And other Terms of Service.","title":"Catstronauts REST API","usagePlans":["bronze","gold","silver"]}]}
    
  6. Follow the steps in Verify external authentication to retrieve your ID token.

  7. Send another request to the /v1/apis endpoint. This time, you provide the ID token that you retrieved in the previous step in the Cookie request header. In your CLI output, verify that you also see the petstore API, because now, you are successfully authenticated and authorized to see this private API.

    curl -vik -H "Cookie: ${ID_TOKEN}" --resolve developer.example.com:80:$INGRESS_GW_IP http://developer.example.com:80/v1/apis
    

    Example output:

    [{"apiProductDisplayName":"Catstronauts Course Tracks","apiProductId":"tracks","apiVersions":[{"apiId":"tracks-v1","apiVersion":"v1","contact":"support@example.com","customMetadata":{"compatibility":"None"},"description":"REST API for Catstronauts to retrieve data for tracks, authors and modules.","license":"License info, such as MIT","lifecycle":"Supported","termsOfService":"You must authenticate to use this API! And other Terms of Service.","title":"Catstronauts REST API","usagePlans":["bronze","gold","silver"]}]},{"apiProductDisplayName":"Pet Store","apiProductId":"petstore","apiVersions":[{"apiId":"petstore-v1","apiVersion":"v1","contact":"support@example.com","customMetadata":{"compatibility":"None"},"description":"Totally awesome API for all things pets!","license":"License info, such as MIT","lifecycle":"Supported","termsOfService":"You must authenticate to use this API! And other Terms of Service.","title":"Pet Store REST API","usagePlans":["bronze","gold","silver"]}]}]
    

Next steps

If you have not already done so, create a frontend for the developer portal.

When you are done with trying out Portal, you can clean up all of the resources that you created.