CIBA-bash : a bash client for the CIBA OpenId Connect protocol
TL;DR : our ciba-bash implementation is available here : https://github.com/please-openit/ciba-bash
CIBA : Client Initiated Backchannel Authentication
What is the goal ? Well… People will think that method is close to device code authentication, a way to authenticate a user without a UI.
Really ? Device code without a UI ? hum… no, device code needs a UI ! Remember, we need a way to display a QRCode or at least a code, then the user uses another UI for login (IE : smartphone).
CIBA uses another mechanism, a Client calls another backend application for authentication.
https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html
sequenceDiagram
Application->>IdentityProvider: Authentication (scopes, username, message)
IdentityProvider->>Relying Party: POST authentication to http backchannel uri
Relying Party->>IdentityProvider: HTTP 201
IdentityProvider->>Application: Response (interval, auth_req_id, expires_in)
Application->>IdentityProvider: Poll for a token with /token
IdentityProvider->>Application: wait
Relying Party->>Authentication Device: Ask user
Authentication Device->>Relying Party: SUCCEED/UNAUTHORIZED/CANCELLED
Relying Party->>IdentityProvider: SUCCEED/UNAUTHORIZED/CANCELLED
Application->>IdentityProvider: Poll for a token with /token
IdentityProvider->>Application: send access token/refresh token
So, the application does not need any user interface, the “relying party” is in charge of authentication and it opens new ways of authentication, for new user experience. Maybe send a push notification directly to the smartphone.
Are you starting to see the possibilities ? Let’s take a look at an example with bash.
The application (IE, the online shop) asks the identity provider for an external authentication.
This is done by using “backchannel endpoint” on Keycloak, a POST request with :
- client_id
- client_secret
- username : the user you want to authenticate
- scopes
- a binding message to transmit
Keycloak will ask an external backend, called the “relying party” with an POST request containing :
- scopes
- the message in “binding_message” field
- the user in “login_hint”
- An authorization bearer token, needed for the answer
This “relying party” is in charge of authentication, for example sending a push notification to the user device. When the user is authenticated, the “relying party” sends a POST request to Keycloak with :
- the authorization bearer token got previously
- the status of the authentication
Keycloak tells the application (with a request if in “ping” mode, or on an answer if in “poll” mode) and sends back a token.
Launch a Keycloak with :
./kc.sh start-dev --spi-ciba-auth-channel-ciba-http-auth-channel-http-authentication-channel-uri=http://127.0.0.1:8081
Then, you need a private client with the CIBA protocol enabled
And of course, a single user.
Launch “relying-party.sh” script, it uses netcat and jq.
./relying-party.sh --ciba-callback-endpoint http://127.0.0.1:8080/realms/master/protocol/openid-connect/ext/ciba/auth/callback
First, it launches a local server on port 8081, waiting for a POST request.
echo -e 'HTTP/1.1 201 OK\r\n' | nc -l 8081
After, this app will be in charge of authentication, keep it open in a terminal.
note : if this script does not answer 201/OK, Keycloak will return a 503 error at the next step
By launching “ciba-auth.sh” script, you will :
- make the CIBA auth request
- get the response, with interval, expiration and the authentication request id
- launch a poll job for the token response.
./ciba-auth.sh --backchannel-authentication-endpoint http://127.0.0.1:8080/realms/master/protocol/openid-connect/ext/ciba/auth --token-endpoint http://127.0.0.1:8080/realms/master/protocol/openid-connect/token --client-id private --client-secret iq0wvuhkASCPeKJNunCx3wJO6qTGRiSF --username please-open.it --scope openid --hint please_auth
note : you can use –openid-endpoint with the URL http://127.0.0.1:8080/realms/master/.well-known/openid-configuration instead of –backchannel-authentication-endpoint and –token-endpoint
curl --location --request POST "$BACKCHANNEL_ENDPOINT" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode "login_hint=$USERNAME" \
--data-urlencode "scope=$SCOPE" \
--data-urlencode "binding_message=$HINT" \
--data-urlencode 'is_consent_required=true'
This returns :
{
"auth_req_id": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..Tu1sCuk2JlPC4O3mTn8nrQ.OSSM58GCFn9oUWh4WPDFEHMhj9zUDQR3zlJimp_Vu1b6zQuCA20xuZfgZHjUs2v2YezmeZzqkhA8c1g8BgmVTIiO3dM0JcYANqY09Tnx2qVVLegBXFYS0ngtkn4KFG_bJUyApMookzFUo4Hk_PkLV6IpnuKyxNTaxA2AbsOEKXVrsVYWv7HmRGtknCi9PVg-Pxs5jDIPRKSCH4CsdGRCpzETgcLXsB0eJ7_x38Z9vo7R5nBPU-0EGXU9frCisfpjIL6jM5u9upANUITuWAr-6QH37-LiPbXp0zKa69ZrxgnhzQuaoo1ES7Pk3iXixV20K8AtcLpSdU9Qh9Cqy3uICspqPyI45tNn0DSUN6FvjXKVRT_VXqi5xJQVjBrdpK12VSA7kdvy4LQN5o1K-R3ZB_kKtQ2x8qsgJSS_8d2G-llm_XLMU7XaIE8tV22H98ee_xb0O6eEosrrjvQQ8rxRAowFupp3uNgGmx6Am_pPGPOJAnuf2yyzxZdIm6H7eriKBoBdb9EM5x6LNX-pRRZxYbJoVAYvBNaaR-K062L0gjv3h6wFbmCFIbdfAV1Vb50TdMH2k_YkMVRJqINY5FC0a__zaN2ma49cmJOtGeArrLiaaR7nFZ8efKu9opE-gHd3oUhsOIuUMJ2ALseApqfGB4j3z8lRqpyRa_u1tFhpZmw8N6PU935KDpdLKILjNQ4400j7C_L65ORKGgrA-ElNixgDhkv2kQFrbpIeKi1ZirB6SGE2ZRTE_-snrAAmiqZg6od81D-nG16W2LpEmxWrpnQoRsWji0ZJu8CZ2Kt770ygUc9QxtxSqbMPCJ2XezHx7NCfE0fvskZ7AS27G4Llxg3xML1Q4r2nxRL8Xx8IRj8bqXsIn6fYfcGys165rQX2.u36LQBjtX80qbj3FK234bQ",
"expires_in": 120,
"interval": 5
}
Note : the auth_req_id is a JWT token… empty of content !
Start a loop, with the information ontained previously. This loop polls on the “/token” endpoint
while ((LOOP<EXPIRES_IN))
do
OUTPUT=$(curl --location --request POST "$TOKEN_ENDPOINT" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' \
--data-urlencode "auth_req_id=$AUTH_REQ_ID" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET")
echo $OUTPUT | jq
if [[ $OUTPUT != *"pending"* ]]; then
break
fi
sleep $INTERVAL
LOOP=$LOOP+$INTERVAL
done
backchannel script has received an authentication request with :
- the username
- an authorization token (in header Authorization)
- scopes
- a binding message
{
"scope": "openid roles profile email",
"binding_message": "please_auth",
"login_hint": "user",
"is_consent_required": "true"
}
For user please-open.it : please_auth (Succeed/Unauthorized/Cancelled)
In the “real life”, the application will send, for example, a push notification on your smartphone to ask you if you authorize the application or not.
After the answer app send a POST request to Keycloak with :
- Authorization bearer
- the answer
The poll job receive a token during the poll job, that’s it, the user is authenticated.
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ4N0dPSW9OZUhIYkFvMjM0UWlrRTk1TW5VVnh6bjVQb1Bsb2llSnVTMlBNIn0.eyJleHAiOjE2NjY3MzkyODAsImlhdCI6MTY2NjczOTIyMCwiYXV0aF90aW1lIjoxNjY2NzM5MjIwLCJqdGkiOiJhNjE0MWE5MC1mM2YwLTQwMWYtYTQzMy0wN2Q5OThkNjE5Y2UiLCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvcmVhbG1zL21hc3RlciIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI5Nzk2YmE3OC04NGM1LTRiZWItYTNjMy04NGFmMzczY2Q1NDEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwcml2YXRlIiwic2Vzc2lvbl9zdGF0ZSI6IjUwNGJmYzIwLTcwZmItNGZhZi1hYTk0LTQ1NTI3YzM2YTFjOSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cHM6Ly9wbGF5Z3JvdW5kLnBsZWFzZS1vcGVuLml0Il0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLW1hc3RlciIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBlbWFpbCBwcm9maWxlIiwic2lkIjoiNTA0YmZjMjAtNzBmYi00ZmFmLWFhOTQtNDU1MjdjMzZhMWM5IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.XKGRAFEcYOqC-oALMuXicOk8XiM3IGedfGMwyoOUayohIsjrQo_ABtuljsemPBNUPS7OQrLiKZIUuZYyy8VogkbeKfiwKtcZBVa5bV_Id8H2P7fR2IEZLqv8h-G1q_Pkc5RDyciicHKRV8R25y8_txOCCtpZxP6aMGv1O5lBTFeUmAshbCDLV-bMQZN6u7R9-5GPNGSSxTlDA1o49mlTl21YoFxiJLl69-C84QMXvxtu-h4xy7bKuk2BadNSN8rxLpwj3MXwDL29zhq-DdTavo3A7pE8wbKEHoVfkwrB67_vvTK7HoMaP0k2UfDa2bDOVnNaBkVsExq0j3eMBMT5DA",
"expires_in": 60,
"refresh_expires_in": 1800,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0NGM5MDk2Ny0yMDQyLTQwNTMtYmExZi1iNjU0MWUyM2YwYjIifQ.eyJleHAiOjE2NjY3NDEwMjAsImlhdCI6MTY2NjczOTIyMCwianRpIjoiNzc0ZTMzZjQtNGQ3Mi00ZGFhLWE3OGUtMjAzNTY0YzIyYjRhIiwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MDgwL3JlYWxtcy9tYXN0ZXIiLCJhdWQiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvcmVhbG1zL21hc3RlciIsInN1YiI6Ijk3OTZiYTc4LTg0YzUtNGJlYi1hM2MzLTg0YWYzNzNjZDU0MSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJwcml2YXRlIiwic2Vzc2lvbl9zdGF0ZSI6IjUwNGJmYzIwLTcwZmItNGZhZi1hYTk0LTQ1NTI3YzM2YTFjOSIsInNjb3BlIjoib3BlbmlkIGVtYWlsIHByb2ZpbGUiLCJzaWQiOiI1MDRiZmMyMC03MGZiLTRmYWYtYWE5NC00NTUyN2MzNmExYzkifQ.SVb51lxEwinAbMlhxQhSmmdhq9QOL60XTrK4x00G5QU",
"token_type": "Bearer",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ4N0dPSW9OZUhIYkFvMjM0UWlrRTk1TW5VVnh6bjVQb1Bsb2llSnVTMlBNIn0.eyJleHAiOjE2NjY3MzkyODAsImlhdCI6MTY2NjczOTIyMCwiYXV0aF90aW1lIjoxNjY2NzM5MjIwLCJqdGkiOiI5YTg2MWFjNC04OWFjLTRkZjAtODFiZC1mYmJkMjU3YWYwYzMiLCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvcmVhbG1zL21hc3RlciIsImF1ZCI6InByaXZhdGUiLCJzdWIiOiI5Nzk2YmE3OC04NGM1LTRiZWItYTNjMy04NGFmMzczY2Q1NDEiLCJ0eXAiOiJJRCIsImF6cCI6InByaXZhdGUiLCJzZXNzaW9uX3N0YXRlIjoiNTA0YmZjMjAtNzBmYi00ZmFmLWFhOTQtNDU1MjdjMzZhMWM5IiwiYXRfaGFzaCI6InRrZTlUQ1lfZWFYdFVKUDk5Q0VnM1EiLCJhY3IiOiIxIiwic2lkIjoiNTA0YmZjMjAtNzBmYi00ZmFmLWFhOTQtNDU1MjdjMzZhMWM5IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.TAx3lAQYRrUcZDUVUaajPhNh5vjJoEq-1TaIXxRSuFBHWGTVQk74midfup9F7W6c4facghl-yZaY9urxPDrvEbvDf_Ti1N_HnDhuYMVwpkJN3gRefriSHdX-sdw_1cGa8zaMqZi29ovHwtRvdqUZQXDf1NXJckhWrui0s2wByS8-yI0G0OISU16EjlIM1L4UZdmu4HneK4NoOnmf-IqI9h3yxjVmW8Q-k3TxOGk_STZsvyY6be8cr7c1nDvtg4dLKdFFUryB0gTJjGAgcL04a1pQOTBBDOYQiHV4kk3WlRd28IcSD_J2-IOnQra8_2OrBS-BALjjd6Mfw9YVi_0r2w",
"not-before-policy": 0,
"session_state": "504bfc20-70fb-4faf-aa94-45527c36a1c9",
"scope": "openid email profile"
}
if the user said “unauthorize” or cancel the job, the answer is :
{
"error": "access_denied",
"error_description": "not authorized"
}
During this example, you noticed that you never put any user password. After answering “s” for Succeed, the application got a token for the user directly.
It means that the “relying-party” is in charge of authentication, by any method it has. If the user is already authenticated, verify the token, refresh it, or ask for a new authentication but also send a push notification for agreement validation. That’s why CIBA is used for many validation processes.
Is it dangerous ?
The protocol itself could be if the relying party is not secured by design. It is in charge of the whole authentication process, a bad implementation (like this example) could authenticate any user without asking for credentials.
So, this protocol with a great implementation is a real big improvement for SSO.