What is API Gateway?

API Gateway is a server that sits between clients and back-end services, routing requests and handling cross-cutting concerns like security, rate limiting, and monitoring. It acts as a single entry point for all clients, simplifying the management of API traffic and enhancing security.

What is IDCS/IAM?

Identity Cloud Service (IDCS) and Identity and Access Management (IAM) are Oracle’s platforms for managing identities and access control. They provide features like authentication, authorization, and policy enforcement, which are essential for securing APIs.

What are JWTs, Scopes, and Claims?

JSON Web Tokens (JWTs) are compact, URL-safe means of representing claims to be transferred between two parties. They are commonly used for authentication and information exchange. Scopes define the level of access granted to a client, while claims are pieces of information asserted about a subject, typically the user.

Quick Answer: Implementing JWT with Scopes and Claims in IDCS/IAM

To implement JWT with scopes and claims in IDCS/IAM, follow these steps:

1. Configure IDCS to issue JWT tokens with the required scopes and claims.
2. Set up the API Gateway to validate these JWT tokens.
3. Ensure that the API Gateway enforces the scopes and claims to control access to your APIs.

How do you configure IDCS to issue JWT tokens with scopes and claims?

Configuring IDCS to issue JWT tokens involves setting up applications, defining scopes, and configuring claims.

Step-by-step Guide

Configure the client

First, create an application in IDCS and configure it to issue JWT tokens.

1. Log in to the IDCS console.
2. Navigate to Applications and create a new application.
3. In the JWT settings, enable JWT token issuance.
4. Define the scopes required for your application.
5. Configure the claims to include necessary user information.

Request the token

Use the OAuth 2.0 client credentials flow to request a JWT token from IDCS.

Example request:

curl -X POST \
  https://idcs-tenant/oauth2/v1/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=read write&client_id=your-client-id&client_secret=your-client-secret'

Validate the response

Check the response to ensure you receive a valid JWT token.

How do you set up the API Gateway to validate JWT tokens?

Setting up the API Gateway to validate JWT tokens involves configuring policies and filters to enforce security.

Step-by-step Guide

Configure the API Gateway

Set up the API Gateway to accept and validate JWT tokens.

1. Log in to the API Gateway console.
2. Create a new API or select an existing one.
3. Add a JWT validation policy to the API.
4. Define rules to validate scopes and claims.
5. Test the configuration to ensure it works as expected.

Example JWT Validation Policy

Here is an example of a JWT validation policy in YAML format:

policies:
  - name: jwt-validation
    type: jwt-validation
    properties:
      issuer: https://idcs-tenant/oauth2/v1
      audience: your-audience
      scopes:
        - read
        - write
      claims:
        - name: user_role
          value: admin

How do you enforce scopes and claims in the API Gateway?

Enforcing scopes and claims ensures that only authorized clients can access your APIs and that they have the appropriate permissions.

Step-by-step Guide

Define Access Control Rules

Set up access control rules based on scopes and claims.

1. Identify the scopes and claims required for each API endpoint.
2. Map scopes to permissions and claims to roles.
3. Apply these rules in the API Gateway configuration.

Example Access Control Rules

Here is an example of access control rules in YAML format:

accessControl:
  rules:
    - path: /api/resource
      methods: [GET, POST]
      scopes:
        - read
        - write
      claims:
        - name: user_role
          value: admin

Security Considerations

Protecting JWT Tokens

Ensure that JWT tokens are protected by following these best practices:

• Use HTTPS to encrypt the communication between clients and the API Gateway.
• Store JWT tokens securely and avoid exposing them in logs or client-side storage.
• Regularly rotate the signing keys used to sign JWT tokens.

Validating JWT Tokens

Validate JWT tokens in the API Gateway to ensure their authenticity and integrity:

• Verify the signature of the JWT token using the public key provided by IDCS.
• Check the expiration time (exp claim) to ensure the token is still valid.
• Validate the issuer (iss claim) to ensure the token was issued by the correct authority.
• Validate the audience (aud claim) to ensure the token is intended for your application.

Enforcing Scopes and Claims

Enforce scopes and claims to control access to your APIs:

• Ensure that the scopes included in the JWT token match the required permissions for the API endpoint.
• Validate that the claims included in the JWT token meet the criteria defined in your access control rules.

Troubleshooting Common Issues

Invalid JWT Token

If you encounter an invalid JWT token error, check the following:

• Ensure that the JWT token is correctly signed and not expired.
• Verify that the issuer and audience claims match the expected values.
• Check that the JWT token contains the required scopes and claims.

Access Denied

If you encounter an access denied error, check the following:

• Ensure that the JWT token contains the required scopes and claims.
• Verify that the access control rules in the API Gateway are correctly configured.
• Check that the user has the necessary permissions to access the API endpoint.

Best Practices

Use HTTPS

Always use HTTPS to encrypt the communication between clients and the API Gateway.

Rotate Signing Keys

Regularly rotate the signing keys used to sign JWT tokens to prevent unauthorized access.

Monitor API Usage

Monitor API usage to detect and respond to suspicious activity.

Conclusion

Protecting APIs with API Gateway using IDCS/IAM JWT with scopes and claims provides a robust and flexible security solution. By following the steps outlined in this guide, you can ensure that only authorized clients can access your APIs and that they have the appropriate permissions.

That’s it. Simple, secure, works.