BankID On Mobile Customization

The look and feel of BankID On Mobile can be customized by merchants if they choose to do so.

The default user-experience is a BankID-branded dialog which includes the following screens:

The merchant can implement their own versions of these screens. An example can be seen in the following screens:

Merchant implementation

The merchant must provide an endpoint where the custom GUI is located. E.g. https://www.example.local/obim. This gui needs input-fields for mobile number and date of birth.

The user is redirected to this endpoint with a query parameter named sid at the start of BIM (BankID on Mobile) authentication. E.g. https://www.example.local/obim?sid=bcc2cd6e-433f-4565-910b-11b050f62ed5

The sid parameter can then be used in the /api/obim APIs to perform a BIM login.

The following flow describes a typical login flow. For description of all possibilities please read the API documentation.

1. An authentication flow is started at the OIDC authentication endpoint.

2. BankID on mobile is used either by directly using the login hint BIM or if the user selects the BankID on Mobile option in the identity provider selector.

3. The user will be redirected to the custom GUI endpoint. E.g. https://www.example.local/obim?sid=bcc2cd6e-433f-4565-910b-11b050f62ed5

4. Typically the user will enter their phone and birth date in the GUI provided by the merchant.

4. The merchant should call the initialize endpoint with sid, phone and birth date parameters to initialize BankID on mobile.

5. The user then has to log in with BankID on their phone.

6. The merchant can query the status endpoint every few seconds to check if the login is finished. 

7. The merchant needs to know where it should redirect the user once the login is finished.

8. The merchant should then redirect the user to the return url retrieved in step 7. after adding the sid query parameter to the url. 

BankID Mobile IDP API

Cross-Origin Resource Sharing (CORS)

URIs used in CORS requests must be registered as "Valid Redirect URIs" on the client in OIDC Client Administration.

POST api/obim/initialize - prepare BankID-server\FOI for a session with BankID Mobile

Content-type: application/x-www-form-urlencoded

Example: https://oidc-ui-preprod.bankidnorge.no/api/obim/initialize

Response content-type: application/json

GET /api/obim/chkHint - Check if the end user can be identified based on the login hint given

If both mobile number and birthdate has been provided in login_hint the client does not need to ask the user for this.

Content-type: application/x-www-form-urlencoded

Response content-type: application/json
Returns a Map of the login hints found

Example https://oidc-ui-preprod.bankidnorge.no/api/obim/chkHint

GET /api/obim/{sid} - Used to poll the status of BankID Mobil authentication

Example: https://oidc-ui-preprod.bankidnorge.no/api/obim/9d1c59e4-6e18-4f6a-9225-a73eacb2a50c

Returns httpstatus 200 if and only if BankID Mobile is finished, either caused by error or OK.

Furthermore the client should use the returnURL to finish. The returnURL can be fetched from the session api.

POST api/obim/cancel - signal from GUI that the user chose to cancel the BankID Mobil dialogue

This will raise a flag in the session triggering a redirect back to the choose screen. The client should redirect the user to the returnURL to finish. The returnURL can be fetched from the session api.

Example https://oidc-ui-preprod.bankidnorge.no/api/obim/cancel