Onboard an application with Charmed Hydra

This guide assumes that your application supports OAuth 2.0 and OpenID Connect (OIDC) protocols.

If your application has not yet adopted these standards, you’ll first need to:

  • Enable your application to make an authorization request to an OAuth Server.

  • Implement a callback endpoint (redirect_uri) that captures the authorization code received from the OAuth 2.0 Server (Hydra) and exchanges it for tokens.

Note

The recommended libraries include:

To let your application authenticate with the Identity Platform, you must register it as an OAuth client in Hydra — the OAuth 2.0 and OIDC Server.

You can do this in one of two ways:

  • Integrate your charmed application with oauth interface.

  • Use the create-oauth-client Juju action provided by Charmed Hydra.

Note

The preferred approach is to integrate your charmed application with Hydra through the oauth interface, which automatically manages client registration based on the provided configuration.

The Juju action and oauth interface offer the following parameters:

  • audience: A list of the audiences your client is allowed to request.

  • grant-types: A list of allowed grant types. Default: ["authorization_code"]

  • redirect-uris: A list of your application’s callback URLs that Hydra is allowed to redirect to.

  • response-types: A list of the allowed response types for the client. Default: ["code"]

  • scope: A list of scopes the client is allowed to request. Refer to this article for more information. Default: ["openid", "profile", "email", "phone"]

  • token-endpoint-auth-method: The authentication method the client is allowed to use at the token endpoint. One of client_secret_post, client_secret_basic, none (for public clients).

  • client-secret: You can optionally provide a secret for your confidential client. If not provided, one will be autogenerated.

You can find detailed explanations of these parameters in the OIDC documentation.

Choosing the right grant type(s)

Depending on what your application does, you’ll need to choose one or more grant types:

  • For human users interacting via browser-based flows, use the authorization_code grant type.

  • For machine-to-machine authentication and service accounts, use the client_credentials grant type.

  • Devices with limited input (TVs, consoles, etc.) can leverage the urn:ietf:params:oauth:grant-type:device_code grant type to enable the device flow.

  • The refresh_token grant type allows your app to get new access tokens without requiring the user to re-authenticate.

Note

You can define multiple grant types for a single client by specifying them as a list (e.g. ["authorization_code", "refresh_token"]), allowing the client to support multiple OAuth flows.

Register your OAuth client

Once you know the right grant types and other parameters, run the create-oauth-client action:

juju run hydra/leader create-oauth-client \
  grant-types='["authorization_code","refresh_token"]' \
  redirect-uris='["https://your-app.example.com/callback"]' \
  response-types='["code"]' \
  scope='["openid","profile","email"]' \
  token-endpoint-auth-method="client_secret_basic"

The action will return your new client’s ID and secret, which you can use to configure your application.

Update your OAuth client

If needed, you can update your client configuration by running:

juju run hydra/leader update-oauth-client \
  client-id="your-client-id" \
  client-secret="your-client-secret" \
  grant-types='["authorization_code","refresh_token"]' \
  redirect-uris='["https://your-app.example.com/callback"]' \
  response-types='["code"]' \
  scope='["openid","profile","email"]' \
  token-endpoint-auth-method="client_secret_basic"

Warning

Any parameters you omit during an update will be reset to their default values.

Delete your OAuth client

You can delete your OAuth client with:

juju run hydra/leader delete-oauth-client \
  client-id="your-client-id"