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.netand the adminjane, whose verified email isjane@acme.example; use your own address and account wherever you see them; - a terminal with
curl,opensslandpython3.
Register the app
- In Sovrain, open Open admin, then Applications, then Add application.
- Enter Application name
My first app, Slugmy-first-app, set Application type to OpenID Connect (SSO) and select Create application. - On the Relying Party (RP) tab, under Redirect URIs, select Add redirect URI, enter
http://localhost:8000/callbackand select Add. Sovrain accepts plainhttponly forlocalhost. - Under Client registration, next to Client secret, select Generate and copy the secret.
- 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
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"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.
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.jsonLook 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:
issis your organization andaudis your client ID: the token was made for your app;subis the person’s permanent id; an app keeps it to recognize the person next time;amris["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
- Add sign-in with OpenID Connect to your app with a real redirect URI and a library.
- Claims and attributes: every claim Sovrain can send.
- Require two-step sign-in from your app,
so that
amrsays more thanpwd.