Connect an identity provider

Goal

For platform teams. In this task you prepare your identity provider. You give Joomiz the values that it needs. Then people can sign in to the CLI and to the dashboard.

Joomiz signs people in with OAuth 2.0. It does not keep passwords. Your identity provider knows the people, and Joomiz reads the token that the provider issues.

Before you start

You have an identity provider that supports OAuth 2.0 and publishes an OpenID Connect discovery document.
You can create clients, scopes and roles there.
You know the public address of the dashboard. Deploy the dashboard shows where it comes from.

Steps

Know who signs in how

Who	How they sign in	Type of client at the provider
A person with the CLI	The device authorization grant (RFC 8628). `joomiz login` prints a web address and a code. The person opens the address in a browser and enters the code.	A public client. It has a client ID and no secret.
A person with the dashboard	The authorization code flow with PKCE. The dashboard service sends the browser to the provider, and gets the tokens when the person comes back.	A confidential web client. It has a client ID and a client secret.
The control plane	It signs nobody in. It accepts the access token of the person, and it reads the roles in it.	None.

In both ways the control plane receives the access token of the person, so the audit trail names the person.

Offer what Joomiz reads

Your identity provider must offer:

A discovery document at the issuer address with /.well-known/openid-configuration at the end.
The signing keys of its tokens, at the address that the discovery document names. The control plane reads them.
A token endpoint. For the CLI, the discovery document must also name a device_authorization_endpoint. The CLI uses the addresses in the document, and it refuses an address that does not start with https.
Refresh tokens for the scope offline_access, so that the CLI and the dashboard can renew a sign-in.
An authorization endpoint that accepts PKCE, for the dashboard.

Create the roles

Joomiz knows two kinds of role. Create them at your provider, and give them to people:

Role	Who gets it
`operator`	The people of the platform team.
`owner:<team>`	The people of a feature team. Create one role for each team. `<team>` is the `application.owner.id` that the team writes in its `joomiz.yaml`, for example `owner:finance-team`.

The roles travel in the access token. The setting joomiz.auth.provider says where. With generic_oidc, the control plane reads the list realm_access.roles. With the default value, it reads the claim roles. Settings reference lists the setting.

The control plane records the ID of the user in the audit trail. It reads the claim oid with the default value of the setting, and the claim sub with generic_oidc. Use a stable value that names one person.

Give Joomiz the values

For	You give	Where it goes
The control plane	The issuer address, the audience and the provider value.	The settings `joomiz.auth.issuer-uri`, `joomiz.auth.audience` and `joomiz.auth.provider`. Deploy the control plane shows them.
The CLI	The issuer address (it must use `https`), the client ID of the public client, and the scopes.	The variables `JOOMIZ_AUTHORITY`, `JOOMIZ_CLIENT_ID` and `JOOMIZ_SCOPE` of each person, or the options of `joomiz login`. CLI reference lists them. Keep `offline_access` in the scopes.
The dashboard	The issuer address, the client ID and the client secret of the web client, the scope, and the audience.	The settings `joomiz.dashboard.oauth.*`. Deploy the dashboard shows them and says how to give the secret.

The access tokens that your provider issues for these clients must carry the audience of the control plane in the claim aud. The scope of the dashboard asks for the scope of the API of Joomiz and offline_access. It does not ask for openid.

For the web client of the dashboard, register this redirect address: the public address of the dashboard, with /login/callback at the end.

Check

Get a token for an operator, as the CLI would. joomiz login shows the steps. Sign in and get access shows the output.
Call the control plane with the token. Read the token into a variable without showing it:

read -rs JOOMIZ_TOKEN
export JOOMIZ_TOKEN

curl -s -w '\nHTTP %{http_code}\n' --variable '%JOOMIZ_TOKEN' --expand-header 'Authorization: Bearer {{JOOMIZ_TOKEN}}' "$JOOMIZ_SERVER_URL/provisioners"

An operator gets 200 and the list of provisioners:

{"items":[]}
HTTP 200

Do the same with the token of a person who has only a role owner:<team>. The answer is 403, because the list of provisioners is for operators. That shows that the roles reach the control plane.
Open the address of the dashboard, sign in, and open the page Overview.

Troubleshooting

Symptom	Cause	Fix
`403` and the title `No Joomiz role`	The token has no `operator` role and no `owner:<team>` role. Often the role is not in the token, or it is in another claim.	Give the user the role. Check the claim that holds it against `joomiz.auth.provider`.
`401` and the title `Unauthorized`	The token does not match the settings `joomiz.auth.audience` and `joomiz.auth.issuer-uri`, or it has expired, or it has no claim with the user ID (`oid` or `sub`).	Compare the `aud` and `iss` claims of the token with the two settings. Check that the token has the user ID claim.
`400` and `Invalid owner`, or `403` and `Not your application`	The role names another team than the `application.owner.id` of the file.	Write the same name in the role and in the file.
`joomiz login` says that the address is not usable and that `https` is expected	The address of the issuer starts with `http`.	Use the `https` address.
`joomiz login` says that the provider does not advertise a device authorization endpoint	The discovery document has no `device_authorization_endpoint`.	Turn on the device authorization grant at the provider.
The sign-in of the dashboard ends on an error page	The redirect address is not registered, the client secret is wrong, or the scope has `openid`.	Check the three.
People are asked to sign in again every few hours	The session of the dashboard or the token ended.	The settings `session.idle-timeout` and `session.absolute-timeout` of the dashboard, and the life of your tokens, decide this.

This is the text of joomiz login with an address that does not start with https:

error: 'http://idp.example.com' is not a usable authority URL; expected an absolute https:// URL. A credential is obtained from this address, so plaintext http is refused rather than warned about.