OAuth 2.0 Token Enforcement for APIs using Keycloak

Question

Pulumi · Accepted Answer

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. When you create APIs that you want to protect with OAuth 2.0, token enforcement ensures that incoming requests to your API have valid access tokens, typically obtained through some prior authentication flow. Keycloak is an open-source identity and access management solution that also supports OAuth 2.0.

In Pulumi, you can automate the setup for Keycloak and configure it for OAuth 2.0 token enforcement by creating a `Realm`, `Client`, and respective `Roles` and `Users`. For API protection, you define a `Client` in Keycloak that represents your API, and you set it up to require valid access tokens for access.

Below is a Pulumi program in Python that sets up a realm, a client, and configures OAuth 2.0 enforcement for an API using Keycloak. This program uses resources from the Pulumi Keycloak provider.

First, ensure you've got the Pulumi Keycloak provider installed:

```sh
# Install using Pulumi CLI
pulumi plugin install resource keycloak v5.2.1
```

Next, you can use the following program in a Python file (e.g., `__main__.py`). It will perform the following actions:

- Create a Keycloak realm.
- Register a confidential client (representing your API) within the realm.
- Set client permissions and access types, configure token settings, and enable service accounts.
- Assign roles to your user and client.

Here is how you can set up such program using Pulumi:

```python
import pulumi
import pulumi_keycloak as keycloak

# Create a new Keycloak Realm.
my_realm = keycloak.Realm("myRealm", realm="my-application", enabled=True)

# Set up a confidential client for your application.
# A confidential client requires a client secret to initiate the login process.
my_client = keycloak.openid.Client("myClient",
    realm_id=my_realm.id,
    client_id="my-application-client",
    name="My Application Client",
    enabled=True,
    description="Client for My Application",
    access_type="CONFIDENTIAL",        # 'CONFIDENTIAL' indicates it's a server-side client
    valid_redirect_uris=["https://my-application/callback"],  # Your application's callback URI
    web_origins=["+"],  # Allows all web origins
    service_accounts_enabled=True,      # Enable service accounts for this client
    client_authenticator_type="client-secret",  # Use client secret for authentication
    standard_flow_enabled=True,         # Enable standard OAuth2 flows for this client
)

# Create a test user within the realm.
test_user = keycloak.User("testUser",
    realm_id=my_realm.id,
    username="test-user",
    email="test-user@example.com",
    enabled=True,
)

# Assign a role to the test user within the realm.
test_user_role = keycloak.Role("testUserRole",
    realm_id=my_realm.id,
    name="test-role",
)

# Bind the role to the test user.
keycloak.UserRoles("testUserRoles",
    realm_id=my_realm.id,
    user_id=test_user.id,
    role_ids=[test_user_role.id],
)

pulumi.export('client_secret', my_client.client_secret)
pulumi.export('realm_name', my_realm.realm)
```

In this program:

- A new realm `my-application` is created that contains all configurations for your application.
- A `client` representing your API is registered as `my-application-client` within the realm. This client has a confidential access type meaning it can maintain a client secret, which is necessary for OAuth 2.0 authorization code flows.
- The `client` is configured to allow service accounts, meaning you can use it for server-to-server authentication.
- A `user` named `test-user` is created to test the OAuth 2.0 flows within the realm.
- A `role` named `test-role` is created and assigned to `test-user`. This allows you to set permission levels based on roles.
- Finally, client secrets and realm names are exported. Client secrets are sensitive and should be handled securely.

Please note that you should have Keycloak running and configured to allow Pulumi to manage resources. Ensure that the Keycloak provider is correctly configured with the Keycloak server's URL and an admin account that has the necessary permissions to create and manage realms, clients, roles, and users.