shonindocs

Use AWS

Applications

People sign in to your own applications with Shonin, as they open the AWS console: one sign-in, with their second factor. Shonin only says who the person is (OpenID Connect). What they may do inside the application stays in the application.

The ID tokens are signed by the installation of your AWS organization, with its KMS key, never by Shonin. The application checks them against the keys the installation publishes. So applications need an AWS organization connected to your Shonin org.

#Add an application

A primary admin adds it in Org settings, panel Applications: enter the client ID of the application and choose Add application. The client ID is the https address of the application's client ID metadata document (see below): Shonin reads the name and the redirect addresses from there. Nothing else to register. Only the applications in this list can sign people in, and only to the redirect addresses of their document. Every change is in the Event log.

To stop an application, choose Remove next to it: it can no longer sign anyone in.

#Give it to people

On the Applications tab, panel Who has each application, an administrator chooses a person or a group and Assign, as for a permission set on an account. Only people who have the application, directly or through a group, can sign in to it. Remove takes it away.

Everyone sees the applications assigned to them on the Applications tab, next to AWS, and opens one with Open. The tabs appear once there is something to show: for administrators when the Shonin org has an application, for everyone else when one is assigned to them.

#For the developers of the application

Configure the application as an OpenID Connect relying party:

  • Issuer: the address shown in Org settings → Applications. It is the installation of your AWS organization (https://<id>.cloudfront.net): discovery at /.well-known/openid-configuration, keys at /jwks.json. The sign-in and token endpoints are on https://<your Shonin org>.app.shonin.ai/oidc.
  • Client ID: the https address of a JSON document you publish, with the same address in client_id:
{
  "client_id": "https://app.example.com/oauth/client.json",
  "client_name": "Example app",
  "redirect_uris": ["https://app.example.com/callback"],
  "application_type": "web",
  "token_endpoint_auth_method": "none",
  "initiate_login_uri": "https://app.example.com/login"
}
  • Flow: authorization code with PKCE (S256), no client secret. Scopes openid, email, profile.
  • ID token: RS256, valid 5 minutes, with sub (stable: use it to recognize the person), email, email_verified, name and given_name. No refresh tokens and no userinfo endpoint: the ID token has everything.
  • Open: with initiate_login_uri in the document, Open goes there with the issuer in iss, and the application starts the sign-in. Without it, Open goes to its client_uri, or to the site of its first redirect URI.
View as Markdown