*for the Decentralised Auth Callout flow

A configurable NATS micro-service that exchanges Identity Provider (IdP) tokens¹ for NATS user authorization JWTs. This component helps implement the decentralised auth callout flow:

1. A prospective NATS user authenticates with their IdP, and passes the obtained token to NATS.
2. This micro-service (re-)validates the IdP token.
3. This micro-service mints a new NATS user access token with specific authorizations.

¹https://www.iana.org/assignments/jwt/jwt.xhtml

The assumption is that implementations of auth callout microservices are almost identical, but for the process of determining which authorizations should be assigned to the minted NATS user access tokens.

This component implements the boilerplate code and using YAML configuration and golang templating, allows construction of JWTs with claims of the form:

claims(natsJwt) = f(claims(idpJwt))

where:

• natsJwt is the JWT sent to the NATS server when establishing a new connection.
• f is a function that extracts and transforms claims from the IdP's Jwt.
• idpJwt is the IdP JWT supplied from the user.

The mock OIDC/OAuth2 service https://oidctest.wsweet.org/ is used to obtain an authenticated JWT id_token.

The example scripts in the scripts/ and examples/ folders demonstrate how to configure, deploy and test this micro-service. These are structred as:

• scripts
  • *-toolkit.sh, helper bash functions.
  • /templates/*, templates to use with vault/openbao and vault-plugin-secret-nats.
• examples
  • /<example_name>
    • /<name>_initial_setup.sh, one-time script to setup decentralised accounts and users
    • /<name>_start_service.sh, configures and starts the auth callout micro-service
    • /<name>_simulate_login.sh, contacts IdP, authenticates, and uses the obtained token to establish a client connection with NATS
    • /run.sh, run all steps in the example

Assuming docker is installed, the examples can be run using: make example-<example_name>.

The RGB.org organisation has three departments that share a single NATS deployment. A department consists of several teams, with each team developing a set of applications.

The blue department has this setup.

• there are three teams: App Team 1, App Team 2, App Team 3

  • they have each developed apps that require access to NATS.
  • users of App Teami's apps have NATS credentials minted by NATS account APPi

• the department has configured and deployed a shared instance of the nats-iam-broker microservice.

  • the microservice connects to NATS using user minter of NATS account MINT_11.
  • minting accounts have an additional user nobody, that has no permissions.

Bob is a member of App Team 3, and wishes to use their in-house app demo-app. This section describes the authentication and authorization flow.

1. Bob launches demo-app.

   • demo-app directs him to OIDC Provider2 for authentication, which Bob completes.
   • demo-app receives back a signed JWT token jwt.provider2.bob.

2. demo-app obtains credentials¹ for MINT_11(nobody) and packages this into a NATS authorization_request (perhaps by calling nats.connect())².

3. NATS creates a connection_id for the Bob's instance of demo-app, and directs the MINT_11(nobody) connection to the blue department's nats-iam-broker microservice. This is because the microservice connects to NATS using MINT_11(minter), and the two have a common NATS account. The connection between NATS and nats-iam-broker is private³.

4. nats-iam-broker microservice receives the request.

   • it unpacks jwt.provider2.bob and validates the token against OIDC Provider2.
   • it performs additional validations, like checking JWT expiry/clock skew, etc.
   • an unsuccessful validation reports an Authorization Violation back to the user.

5. nats-iam-broker microservice mints a new JWT.

   • it inspects Bob's user/profile information in jwt.provider2.bob.
   • it determines that the account to issue+sign the minted token is APP3.
   • it creates a set of unique authorizations for Bob's demo-app usage.
   • it sets a suitable token expiry etc.

6. nats-iam-broker signs the minted JWT, encrypts it for transport and sends it to NATS server.

7. NATS server decrypts³ and validates the nats-jwt, and binds the authorizations to the client's connection_id. Finally, it notifies Bob's instance of demo-app of the successful connection.

¹ although nobody user credentials have no NATS permissions, storing them externally can facilitate key rotation of signing_key(MINT_11).

² a (somewhat) arbitrary decision has been made to pass the third-party JWT in the password field, i.e., nats.Connect(UserCredentials(MINT_11(nobody)), password=jwt.provider2.bob)

³ this uses the XKey field. It is optional but recommended.

This example demonstates a simpler setup consisting of:

• one auth callout microservice MINT, with standard users minter and nobody
• one appliction account APP1

As in the previous example, authorised NATS users are created and signed on-the-fly, following successful validation of the IdP token.

This section describes some (probably common) deployment methods:

• a single golang binary plus a (mergable set of) YAML configuration file(s).
• a docker/podman compose file.
• a helm-chart, see charts/nats-iam-broker/README.md.

NATS accounts must be created locally (with access to keys) and then pushed to the target NATS server. This section is intended as an example/rough-guide and assumes the NATS infrastructure as described in the nats-infra repo is up and running.

1. Create the MYAPP-MINT auth-callout account.

export OPERATOR_NAME=local-operator
export ACCOUNT_NAME=MYAPP-MINT
export NATS_CONTAINER=infra-team-nats-1
export NSC_CONTAINER=infra-team-nsc-admin-1
export OUTPUT_DIR=./nats-secrets

echo Creating account $ACCOUNT_NAME
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jr200/nats-infra/main/scripts/nats-create-account.sh)"

echo Enabling auth-callout for $ACCOUNT_NAME
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jr200/nats-infra/main/scripts/nats-enable-auth-callout.sh)"

echo Fetching signing keys for $ACCOUNT_NAME
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jr200/nats-infra/main/scripts/nats-fetch-signing-creds.sh)"

2. Create the MYAPP account

export OPERATOR_NAME=local-operator
export ACCOUNT_NAME=MYAPP
export NATS_CONTAINER=infra-team-nats-1
export NSC_CONTAINER=infra-team-nsc-admin-1
export OUTPUT_DIR=./nats-secrets

echo Creating account $ACCOUNT_NAME
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jr200/nats-infra/main/scripts/nats-create-account.sh)"

echo Fetching signing keys for $ACCOUNT_NAME
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jr200/nats-infra/main/scripts/nats-fetch-signing-creds.sh)"

3. Start the nats-iam broker instance

podman compose -f compose-iam.yml -p dev-team up -d

Standard go templating is used to construct roles dynamically. Templating functions are listed in the filters module.

The configuration structure is outlined here.

The custom_mapping feature allows you to map custom claim names from your IDP's JWT tokens to standardized claim names in the NATS IAM broker. This is particularly useful when working with IDPs that use custom claim names or URL-based claims.

• You can map any custom claim name from your IDP to any standardized name you prefer
• The mapping is flexible and supports any claim name that appears in your IDP's JWT tokens
• Standard claims (like "name", "email", "sub", etc.) cannot be mapped as they are handled separately by the system
• If a claim isn't mapped, it will be stored with its original name in the CustomClaims map

idp:
  - description: My-Custom-IDP
    client_id: "my-client-id"
    issuer_url: "https://my-idp.example.com"
    custom_mapping:
      "https://mycompany.com/claims/department": "department"
      "https://mycompany.com/claims/employee_id": "employee_id"
      "https://mycompany.com/claims/access_level": "access_level"
      "https://mycompany.com/claims/roles": "roles"
      "https://mycompany.com/claims/groups": "groups"

In this example:

• The custom URL-based claim https://mycompany.com/claims/department will be mapped to department
• The custom URL-based claim https://mycompany.com/claims/employee_id will be mapped to employee_id
• The custom URL-based claim https://mycompany.com/claims/access_level will be mapped to access_level
• The custom URL-based claims for roles and groups are mapped to their standard names

These mapped claims can then be used in your RBAC configuration and role bindings.

When a claim is not explicitly mapped in the custom_mapping configuration, it will be stored with its original name in the CustomClaims map. This is useful when you want to preserve the original claim names or when you don't need to standardize certain claims.

For example, if your IDP JWT contains these claims:

{
  "email": "user@example.com",
  "https://mycompany.com/claims/department": "engineering",
  "https://mycompany.com/claims/employee_id": "12345",
  "https://mycompany.com/claims/access_level": "admin",
  "https://mycompany.com/claims/roles": ["developer", "admin"],
  "https://mycompany.com/claims/groups": ["team-a", "team-b"],
  "https://mycompany.com/claims/custom_field": "custom value"
}

And your configuration only maps some of them:

idp:
  - description: My-Custom-IDP
    client_id: "my-client-id"
    issuer_url: "https://my-idp.example.com"
    custom_mapping:
      "https://mycompany.com/claims/department": "department"
      "https://mycompany.com/claims/employee_id": "employee_id"
      "https://mycompany.com/claims/roles": "roles"
      "https://mycompany.com/claims/groups": "groups"

The resulting claims in the NATS IAM broker will be:

{
  "email": "user@example.com",
  "department": "engineering",
  "employee_id": "12345",
  "roles": ["developer", "admin"],
  "groups": ["team-a", "team-b"],
  "https://mycompany.com/claims/access_level": "admin",
  "https://mycompany.com/claims/custom_field": "custom value"
}

Notice that:

• https://mycompany.com/claims/access_level and https://mycompany.com/claims/custom_field retain their original names because they weren't explicitly mapped
• The mapped claims (department, employee_id, roles, groups) use their standardized names

1. youtube, synadia auth-callout: https://www.youtube.com/watch?v=VvGxrT-jv64
2. youtube: synaida decentralised auth callout: https://www.youtube.com/watch?v=5pQVjN0ym5w
3. natsbyexample: https://natsbyexample.com/examples/auth/callout-decentralized/cli
4. rethinking connectivity 19: https://github.com/synadia-io/rethink_connectivity/tree/main/19-auth-callout
5. mock oidc service: https://lemonldap-ng.org/documentation/latest/testopenidconnect.html