Sovrain
  1. Documentation
  2. Get started

Tutorial

Sign someone in with OpenID Connect from your terminal

Register an app, run the authorization code flow with PKCE by hand and read the ID token Sovrain returns.

In this tutorial we play the part of an application ourselves. We register it in Sovrain, send a person to sign in, catch the answer on our own computer, swap it for tokens with curl and read who signed in. At the end we know every step an OpenID Connect library does for an application.

It takes about 15 minutes.

Before you start

You need:

  • an organization in which you are an admin, for example the one from Create your organization. We use https://acme.sovrain.net and the admin jane, whose verified email is jane@acme.example; use your own address and account wherever you see them;
  • a terminal with curl, openssl and python3.

Register the app

  1. In Sovrain, open Open admin, then Applications, then Add application.
  2. Enter Application name My first app, Slug my-first-app, set Application type to OpenID Connect (SSO) and select Create application.
  3. On the Relying Party (RP) tab, under Redirect URIs, select Add redirect URI, enter http://localhost:8000/callback and select Add. Sovrain accepts plain http only for localhost.
  4. Under Client registration, next to Client secret, select Generate and copy the secret.
  5. On the Access & diagnostics tab, under Group access, select Add group, choose All and select Add.

Now put the client ID and the secret in your terminal, so the commands below can use them:

client_id='<Client ID from Client registration>'
client_secret='<the secret you copied>'

Start something that receives the answer

After signing someone in, Sovrain sends the browser back to the redirect URI. We need something listening there.

In a second terminal, run:

python3 -m http.server 8000

It prints Serving HTTP on :: port 8000 and waits. Leave it running.

Make a PKCE pair

Sovrain requires PKCE: the app proves that the one who asks for the tokens is the one who started the sign-in. In the first terminal, run:

code_verifier=$(openssl rand -base64 48 | tr -d '=+/' | cut -c1-64)
code_challenge=$(printf '%s' "$code_verifier" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

Send someone to sign in

  1. Print the sign-in address:

    echo "https://acme.sovrain.net/oidc/authorize?response_type=code&client_id=$client_id&redirect_uri=http://localhost:8000/callback&scope=openid%20profile%20email&state=tutorial&code_challenge=$code_challenge&code_challenge_method=S256"
    
  2. Open the printed address in your browser and sign in with your Sovrain account if Sovrain asks.

The browser ends on localhost:8000 and shows an error page from Python, File not found. That is expected: our listener has no page to show. The part we need is in the second terminal, which printed a line like this:

"GET /callback?code=WxU9pstf68RDviYG5x9g5vCAhRmaeNJbBo7VAGQmgSaP&state=tutorial&iss=https%3A%2F%2Facme.sovrain.net HTTP/1.1" 404 -

Notice state=tutorial, the value we sent, and iss, the organization that answered.

Swap the code for tokens

The code works once and only for 60 seconds, so do this step right away. If it fails with invalid_grant, open the sign-in address again to get a new code.

  1. Copy the value after code= from the line above, up to &, and run:

    code='<the code>'
    curl -s -u "$client_id:$client_secret" https://acme.sovrain.net/oidc/token \
      -d grant_type=authorization_code \
      -d "code=$code" \
      -d redirect_uri=http://localhost:8000/callback \
      -d "code_verifier=$code_verifier" > tokens.json
    
  2. Look at what came back:

    python3 -c "import json; print(list(json.load(open('tokens.json'))))"
    

You see ['access_token', 'token_type', 'expires_in', 'id_token', 'scope']: Sovrain trusted our app because it had the right secret and the verifier that matches the challenge.

Read who signed in

The ID token says who signed in. Its middle part is plain JSON in base64:

python3 -c "
import base64, json
part = json.load(open('tokens.json'))['id_token'].split('.')[1]
print(json.dumps(json.loads(base64.urlsafe_b64decode(part + '=' * (-len(part) % 4))), indent=2))
"

You see something like this:

{
  "amr": ["pwd"],
  "aud": "ppptmCpk8xkRkrhr3HWEUz",
  "email": "jane@acme.example",
  "email_verified": true,
  "iss": "https://acme.sovrain.net",
  "preferred_username": "jane",
  "sub": "28dbFXKE5EiERJiezF32wZ"
}

Notice:

  • iss is your organization and aud is your client ID: the token was made for your app;
  • sub is the person’s permanent id; an app keeps it to recognize the person next time;
  • amr is ["pwd"]: the person signed in with a password only.

Ask for the user’s details

The access token lets the app ask Sovrain about the person:

access_token=$(python3 -c "import json; print(json.load(open('tokens.json'))['access_token'])")
curl -s -H "Authorization: Bearer $access_token" https://acme.sovrain.net/oidc/userinfo

You see the same person again; curl prints it on one line, here it is split for reading:

{
  "email": "jane@acme.example",
  "email_verified": true,
  "preferred_username": "jane",
  "sub": "28dbFXKE5EiERJiezF32wZ"
}

You can stop the listener in the second terminal with Ctrl+C.

What we did

We registered an app, sent a person to sign in with PKCE, caught the code on localhost, swapped it for tokens with the client secret and the verifier, and read who signed in from the ID token and from userinfo.

Next steps