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
Form parameter | Explanation |
|---|---|
| sid | session ID |
| phone | phonenumber |
| ddmmyy | birthdate |
Response content-type: application/json
Response parameter | Explanation |
|---|---|
Response parameter | Explanation |
| error | true if an error occured |
| merchantReference | The code word to be accepted by the end user |
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
Form parameter | Explanation |
|---|---|
| sid | session ID |
Response content-type: application/json
Returns a Map of the login hints found
Key | Value |
|---|---|
| phone | Mobile number given in login hint |
| ddmmyy | Birthdate given in login hint |
Example https://oidc-ui-preprod.bankidnorge.no/api/obim/chkHint
GET /api/obim/{sid} - Used to poll the status of BankID Mobil authentication
Path parameter | Explanation |
|---|---|
| sid | session ID |
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.
Request parameter | Explanation |
|---|---|
| sid | session ID |
Example https://oidc-ui-preprod.bankidnorge.no/api/obim/cancel