Login
      Contents x
      Client Initiated Backchannel Authentication (CIBA)
      • 22 Nov 2024
      • 10 Minutes to read
      • Print
      • Dark
        Light
      • PDF
      Contents

      Client Initiated Backchannel Authentication (CIBA)

      • Updated on 22 Nov 2024
      • 10 Minutes to read
      • Print
      • Dark
        Light
      • PDF
      Article summary

      CIBA Authentication Request - Bearer token for Web App

      CIBA is an authentication flow defined in https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html

      Use the client_credentials OAuth2 grant type to obtain a CIBA Authentication Request ID.

      Example:

      curl --request POST --url https://connect.visma.com/connect/ciba --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials&scope=openid visma_api:read&login_hint=john.doe@example.com&binding_message=ABC123&client_id=demoapp&client_secret=SECRET'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      client_credentials

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of client_credentials.

      scope

      openid visma_api:read offline_access

      • At minimum ask for “openid” scope

      • If you need a refresh token ask for “offline_access”

      • If you want API access add the Interactive API scopes your require

      The “visma_api:read” scope-name above is just an example - check your API documentation for scope(s) to use.

      Remember to enable CIBA + Offline Access (if you need it) in the Developer Portal.

      yes

      CIBA extends OpenID Connect. The list of scopes in the authentication request must therefore contain openid.

      You can also add scopes that Identifies the Visma API access that your application is requesting. Multiple scopes separated by a space.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      login_hint

      john.doe@example.com

      yes

      Identify the email address of the user who it requests to login.

      binding_message

      ABC123

      no

      A human-readable message to be displayed at the consumption device and at the Connect IdP Consent screen. This allows the user to ensure the transaction initiated by the consumption device is the same that the user gives consent to.

      If successful, this call will return a response with the following fields:

      {
    "auth_req_id": "F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1",
    "expires_in": 300,
    "interval": 5
}

      If an error happens, the call will return a 400 Bad Request with the following fields:

      {
    "error": "unknown_user_id",
    "error_description": "Unknown user id"
}

      Error Code

      Description

      unknown_user_id

      The user identifier in login_hint parameter does not exist.

      Token request  - Bearer token for Web App

      Poll the token endpoint for

      Use the urn:openid:params:grant-type:ciba OAuth2 grant type to obtain Access Token.

      Example:

      curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=urn:openid:params:grant-type:ciba&client_id=demoapp&client_secret=SECRET&auth_req_id=F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      urn:openid:params:grant-type:ciba

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of urn:openid:params:grant-type:ciba.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      auth_req_id

      F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1

      yes

      Identifies the unique CIBA Authentication Request ID.

      The CIBA Authenticaton Request must be approved (consent given by the end-user) before your App will receive the Access Token.

      As with any other flow in OpenID Connect, the token request in CIBA may result in an error. In addition to the error codes defined as part of the OAuth 2.0 specification, CIBA considers the following as applicable as well:

      Error Code

      Description

      authorization_pending

      The user has not yet been authenticated, and the authorization request is still pending.

      slow_down

      The authorization request is still pending, and the client must increase the interval for polling requests by at least 5 seconds.

      expired_token

      The transaction (auth_req_id) has expired. The client must start over with a new Authentication Request.

      access_denied

      The user did not consent to the authorization request.

      invalid_grant

      The provided auth_req_id is invalid or was issued to another client.

      invalid_request

      The server may return this error if the client does not respect the polling interval. When receiving an invalid_request, the client must stop polling for the auth_req_id.

      If the token request is valid, and the user has been authenticated and has consented to the request, a successful response just as with any other OpenID flow will contain the following fields:

      { 
 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVENDc....7MTOBbdd5mgb2CHzxL0RFjs24pqC1pCeUqOjbg",
 "expires_in": 3600,
 "token_type": "Bearer",
 "scope": "visma_api:read" 
}

      CIBA Authentication Request - DPoP token for Web App (DRAFT)

      CIBA is an authentication flow defined in https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html

      Use the client_credentials OAuth2 grant type to obtain a CIBA Authentication Request ID.

      Example:

      curl --request POST --url https://connect.visma.com/connect/ciba --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials&scope=openid visma_api:read&login_hint=john.doe@example.com&binding_message=ABC123&client_id=demoapp&client_secret=SECRET'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      client_credentials

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of client_credentials.

      scope

      openid visma_api:read offline_access

      • At minimum ask for “openid” scope

      • If you need a refresh token ask for “offline_access”

      • If you want API access add the Interactive API scopes your require

      The “visma_api:read” scope-name above is just an example - check your API documentation for scope(s) to use.

      Remember to enable CIBA + Offline Access (if you need it) in the Developer Portal.

      yes

      CIBA extends OpenID Connect. The list of scopes in the authentication request must therefore contain openid.

      You can also add scopes that Identifies the Visma API access that your application is requesting. Multiple scopes separated by a space.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      login_hint

      john.doe@example.com

      yes

      Identify the email address of the user who it requests to login.

      binding_message

      ABC123

      no

      A human-readable message to be displayed at the consumption device and at the Connect IdP Consent screen. This allows the user to ensure the transaction initiated by the consumption device is the same that the user gives consent to.

      If successful, this call will return a response with the following fields:

      {
    "auth_req_id": "F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1",
    "expires_in": 300,
    "interval": 5
}

      Token request  - DPoP token for Web App (DRAFT)

      Poll the token endpoint for

      Use the urn:openid:params:grant-type:ciba OAuth2 grant type to obtain Access Token.

      Example:

      curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=urn:openid:params:grant-type:ciba&client_id=demoapp&client_secret=SECRET&auth_req_id=F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      urn:openid:params:grant-type:ciba

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of urn:openid:params:grant-type:ciba.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      auth_req_id

      F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1

      yes

      Identifies the unique CIBA Authentication Request ID.

      The CIBA Authenticaton Request must be approved (consent given by the end-user) before your App will receive the Access Token.

      As with any other flow in OpenID Connect, the token request in CIBA may result in an error. In addition to the error codes defined as part of the OAuth 2.0 specification, CIBA considers the following as applicable as well:

      Error Code

      Description

      authorization_pending

      The user has not yet been authenticated, and the authorization request is still pending.

      slow_down

      The authorization request is still pending, and the client must increase the interval for polling requests by at least 5 seconds.

      expired_token

      The transaction (auth_req_id) has expired. The client must start over with a new Authentication Request.

      access_denied

      The user did not consent to the authorization request.

      invalid_grant

      The provided auth_req_id is invalid or was issued to another client.

      invalid_request

      The server may return this error if the client does not respect the polling interval. When receiving an invalid_request, the client must stop polling for the auth_req_id.

      If the token request is valid, and the user has been authenticated and has consented to the request, a successful response just as with any other OpenID flow will contain the following fields:

      { 
 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVENDc....7MTOBbdd5mgb2CHzxL0RFjs24pqC1pCeUqOjbg",
 "expires_in": 3600,
 "token_type": "Bearer",
 "scope": "visma_api:read" 
}

      CIBA Authentication Request - Bearer token for Native App (DRAFT)

      CIBA is an authentication flow defined in https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html

      Use the client_credentials OAuth2 grant type to obtain a CIBA Authentication Request ID.

      Example:

      curl --request POST --url https://connect.visma.com/connect/ciba --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials&scope=openid visma_api:read&login_hint=john.doe@example.com&binding_message=ABC123&client_id=demoapp&client_secret=SECRET'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      client_credentials

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of client_credentials.

      scope

      openid visma_api:read offline_access

      • At minimum ask for “openid” scope

      • If you need a refresh token ask for “offline_access”

      • If you want API access add the Interactive API scopes your require

      The “visma_api:read” scope-name above is just an example - check your API documentation for scope(s) to use.

      Remember to enable CIBA + Offline Access (if you need it) in the Developer Portal.

      yes

      CIBA extends OpenID Connect. The list of scopes in the authentication request must therefore contain openid.

      You can also add scopes that Identifies the Visma API access that your application is requesting. Multiple scopes separated by a space.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      login_hint

      john.doe@example.com

      yes

      Identify the email address of the user who it requests to login.

      binding_message

      ABC123

      no

      A human-readable message to be displayed at the consumption device and at the Connect IdP Consent screen. This allows the user to ensure the transaction initiated by the consumption device is the same that the user gives consent to.

      If successful, this call will return a response with the following fields:

      {
    "auth_req_id": "F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1",
    "expires_in": 300,
    "interval": 5
}

      Token request  - Bearer token for Native App (DRAFT)

      Poll the token endpoint for

      Use the urn:openid:params:grant-type:ciba OAuth2 grant type to obtain Access Token.

      Example:

      curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=urn:openid:params:grant-type:ciba&client_id=demoapp&client_secret=SECRET&auth_req_id=F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      urn:openid:params:grant-type:ciba

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of urn:openid:params:grant-type:ciba.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      auth_req_id

      F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1

      yes

      Identifies the unique CIBA Authentication Request ID.

      The CIBA Authenticaton Request must be approved (consent given by the end-user) before your App will receive the Access Token.

      As with any other flow in OpenID Connect, the token request in CIBA may result in an error. In addition to the error codes defined as part of the OAuth 2.0 specification, CIBA considers the following as applicable as well:

      Error Code

      Description

      authorization_pending

      The user has not yet been authenticated, and the authorization request is still pending.

      slow_down

      The authorization request is still pending, and the client must increase the interval for polling requests by at least 5 seconds.

      expired_token

      The transaction (auth_req_id) has expired. The client must start over with a new Authentication Request.

      access_denied

      The user did not consent to the authorization request.

      invalid_grant

      The provided auth_req_id is invalid or was issued to another client.

      invalid_request

      The server may return this error if the client does not respect the polling interval. When receiving an invalid_request, the client must stop polling for the auth_req_id.

      If the token request is valid, and the user has been authenticated and has consented to the request, a successful response just as with any other OpenID flow will contain the following fields:

      { 
 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVENDc....7MTOBbdd5mgb2CHzxL0RFjs24pqC1pCeUqOjbg",
 "expires_in": 3600,
 "token_type": "Bearer",
 "scope": "visma_api:read" 
}

      CIBA Authentication Request - DPoP token for Native App (DRAFT)

      CIBA is an authentication flow defined in https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html

      Use the client_credentials OAuth2 grant type to obtain a CIBA Authentication Request ID.

      Example:

      curl --request POST --url https://connect.visma.com/connect/ciba --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials&scope=openid visma_api:read&login_hint=john.doe@example.com&binding_message=ABC123&client_id=demoapp&client_secret=SECRET'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      client_credentials

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of client_credentials.

      scope

      openid visma_api:read offline_access

      • At minimum ask for “openid” scope

      • If you need a refresh token ask for “offline_access”

      • If you want API access add the Interactive API scopes your require

      The “visma_api:read” scope-name above is just an example - check your API documentation for scope(s) to use.

      Remember to enable CIBA + Offline Access (if you need it) in the Developer Portal.

      yes

      CIBA extends OpenID Connect. The list of scopes in the authentication request must therefore contain openid.

      You can also add scopes that Identifies the Visma API access that your application is requesting. Multiple scopes separated by a space.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      login_hint

      john.doe@example.com

      yes

      Identify the email address of the user who it requests to login.

      binding_message

      ABC123

      no

      A human-readable message to be displayed at the consumption device and at the Connect IdP Consent screen. This allows the user to ensure the transaction initiated by the consumption device is the same that the user gives consent to.

      If successful, this call will return a response with the following fields:

      {
    "auth_req_id": "F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1",
    "expires_in": 300,
    "interval": 5
}

      Token request  - DPoP token for Native App  (DRAFT)

      Poll the token endpoint for

      Use the urn:openid:params:grant-type:ciba OAuth2 grant type to obtain Access Token.

      Example:

      curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=urn:openid:params:grant-type:ciba&client_id=demoapp&client_secret=SECRET&auth_req_id=F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F'

      Parameters:

      Name

      Example Value

      Required

      Description

      grant_type

      urn:openid:params:grant-type:ciba

      yes

      As defined in the OAuth 2.0 specifications, this field must contain value of urn:openid:params:grant-type:ciba.

      client_id

      demoapp

      yes

      The Client ID set when application was registered. Identifies which app is making the request.

      client_secret

      The secret obtained when registering the application

      yes

      This is your application's Client Secret.

      auth_req_id

      F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1

      yes

      Identifies the unique CIBA Authentication Request ID.

      The CIBA Authenticaton Request must be approved (consent given by the end-user) before your App will receive the Access Token.

      As with any other flow in OpenID Connect, the token request in CIBA may result in an error. In addition to the error codes defined as part of the OAuth 2.0 specification, CIBA considers the following as applicable as well:

      Error Code

      Description

      authorization_pending

      The user has not yet been authenticated, and the authorization request is still pending.

      slow_down

      The authorization request is still pending, and the client must increase the interval for polling requests by at least 5 seconds.

      expired_token

      The transaction (auth_req_id) has expired. The client must start over with a new Authentication Request.

      access_denied

      The user did not consent to the authorization request.

      invalid_grant

      The provided auth_req_id is invalid or was issued to another client.

      invalid_request

      The server may return this error if the client does not respect the polling interval. When receiving an invalid_request, the client must stop polling for the auth_req_id.

      If the token request is valid, and the user has been authenticated and has consented to the request, a successful response just as with any other OpenID flow will contain the following fields:

      { 
 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVENDc....7MTOBbdd5mgb2CHzxL0RFjs24pqC1pCeUqOjbg",
 "expires_in": 3600,
 "token_type": "Bearer",
 "scope": "visma_api:read" 
}

      The signed-in end user from the login_hint must give CIBA Consent at the following URI

      The end user must authenticate the CIBA request and grant consent in the identity server.

      The authentication request ID have to be hashed in the following way and provided in query parameter.

      The CIBA Authentication Request ID must be sent in the URI as a SHA256, UTF-8, HEX(Upper case) string appended with “:ciba”. Online test-tool: https://passwordsgenerator.net/sha256-hash-generator/

      Example:

      queryParamRequestId = SHA256(auth_req_id + ':ciba')

Example: SHA256('F5BC9CD6B18943E4D817BF46F2F6867AD97A188B3AB61BF0EDA0856246AC1C6F-1:ciba')

Outputs: 441A7768D5F82D9936B4481DBBBBE2F6D1154CA95AC548274F603151F80FCA97

      Example URI:

      curl --request GET --url https://connect.visma.com/ciba/consent?client_id=demoapp&returnURL=https://www.example.com&auth_req_id=441A7768D5F82D9936B4481DBBBBE2F6D1154CA95AC548274F603151F80FCA97'

      A screen like below will be shown to the user (after sign in or if they already have a session) where they can consent to granting access to the Application.

      DeveloperPortal_CIBA

      Was this article helpful?
      What's Next

      © 2024 Visma

      Change password!
      Changing your password will log you out immediately. Use the new password to log back in.
      Change profile
      Success!
      First name must have atleast 2 characters. Numbers and special characters are not allowed.
      Last name must have atleast 1 characters. Numbers and special characters are not allowed.
      Enter a valid email
      Enter a valid password
      Your profile has been successfully updated.
      Logout