GRP v2.1
General Relying Party version 2.1
API documentation
Document version 1.0
- Introduction
- Web service description
- Autostart token or separate devices
- Authenticate / Sign operations
- AuthenticateResponse / SignResponse
- Collect
- CollectRequest
- CollectResponse
- ProgressStatus
- UserInfo
- ValidationInfo
- GrpFault
- Examples:
- Example authentication (BankID same device)
- Example authentication (BankID separate devices)
- Known Bugs
Introduction
Several providers of electronic ID:s (Finansiell ID-teknik, Verisec, Secmaker) have similar API:s that customers can use to request authentication and signing operations. The GRP service wraps all these API:s into one, making the implementation of the different electronic ID:s much simpler for service providers. Consumers of the GRP API are called Relying Parties (RP:s).
The GRP API is a SOAP interface with three main methods:
· Authenticate - Initiate an authentication process.
· Sign - Initiate a signature process signing some data.
· Collect - Fetch result from the above processes.
Web service description
The WSDL of the GRP service is available here:
https://grpt.funktionstjanster.se/grp/v2.1?wsdl
Autostart token or separate devices
When the client app or browser is on a separate device from the eID app, the unique identifier (like SSN or email depending on provider) must always be included in the authenticate/sign operation. When the clients are on the same device, some providers make it possible to start the client with an "autostart token" that is returned in the response of the Sign and Authenticate methods. The autostart token is then used when starting the eID app, as a parameter in the special URL scheme URL.
Autostart of BankID:
To start the BankID app with an autostart token, the URL should have the following format:
bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]
Autostart for Secmaker NetID:
netid:///?autostarttoken=[TOKEN]&redirecturl=[RETURNURL]
Return URL above is an optional URL that can be opened by the eID app after the operation has finished. For more information about the different eID app scheme URL:s, please see documentation of that provider.
Authenticate / Sign operations
Both the Authenticate and SIgn operations have mostly the same arguments and are used in the same way. The Sign operation uses two additional arguments that contain the data to be signed.
| Argument | Value |
|---|---|
| policy | Relying parties identify themselves for the GRP API using the argument "policy". This is a value assigned by the GRP service operator when signing up. |
| provider | The relying party selects eID provider using the argument "provider". Examples are "bankid", "freja" and "nias". |
| rpDisplayName | The RP display name is a string that is displayed in the eID app when performing a signature or authenticate operation. Since it indicates where the electronic ID is being used it is an important security feature. The display name is normally the name of the RP organization or web site. All relying parties with a GRP account have a default display name that is added when signing up for the service. Additional display names can be ordered from the GRP service provider beforehand. After that, the RP can select the display name to use for each authenticate or sign operation. If no display name is specified, the default display name for that account (policy) will be used. |
| transactionId | A client provided random string unique for the specific AuthenticateRequest or SignatureRequest. UUID format is recommended. The same value is returned in the response and this is used for tracing and logging purposes. |
| subjectIdentifier | User unique identifier, like SSN. For some eID provider it is always required, for others it is only required when eID is on another device. See section about autostart token. |
| endUserInfo | Key-value pairs with information about the user included in the auth and sign requests. Currently only used for IP of the client, but may be extended in the future. Key: "IP_ADDR" Value: IP address of the device connected to RP and wishes to log in or sign. May be different from IP of the device with the eID. |
| requirementAlternatives | Some providers allow RP:s to add requirements to the eID app. Examples are to allow / to not allow fingerprint unlock, specifying which eID CA:s are allowed etc. For the specific options available for different providers, please see the documentation of the provider. |
| userVisibleData | Only used for "Sign" operation. Text to be signed and displayed to user in the eID app. Should be a Base64 encoded UTF-8 string. Max length depends on the eID provider. Example for BankID is 40 000 characters after Base64 encoding. |
| userNonVisibleData | Only used for "Sign" operation. Data to be signed, not displayed to user in the eID app. Should be Base64 encoded. Max length depends on the eID provider. Example for BankID is 200 000 characters after Base64 encoding. |
AuthenticateResponse / SignResponse
Responses to Authenticate and Sign operation contain the same attributes:
| Attribute | Value |
|---|---|
| transactionId | The same transactionId that was provided in the request, used for tracing and logging purposes. |
| orderRef | An order reference that should be used in subsequent calls to the collect endpoint. |
| AutoStartToken | A unique token used by some providers to start the app on the same device. See section "Autostart token or separate devices". |
| qrStartToken | A token used to compute the animated QR code |
| qrStartSecret | A token used to compute the animated QR code |
Collect
After initializing the authentication or sign operations, the collect method should be polled for a result. The recommended time is 2 seconds and it should not be called more often than once every second.
CollectRequest
| Attribute | Value |
|---|---|
| policy | See Authenticate / Sign |
| provider | See Authenticate / Sign |
| rpDisplayName | See Authenticate / Sign |
| transactionId | See Authenticate / Sign |
| orderRef | The value received in Authenticate / Sign response. |
CollectResponse
| Error Attribute | Value |
|---|---|
| transactionId | The transactionId provided in the request, used for tracing purposes. |
| progressStatus | Status of the order, see section "ProgressStatus" |
| userInfo | Basic information about the user, see section "UserInfo" |
| validationInfo | Information about the validation. May contain the actual signature and OCSP response from certificate validation. See section "ValidationInfo". |
| attributes | Key-value pairs with information from the certificate or sign/auth operation. See separate specification of response attributes. |
ProgressStatus
| ProgressStatusType | Value |
|---|---|
| COMPLETE | Operation is complete. |
| USER_SIGN | App has started. Waiting for user to enter PIN or password. |
| OUTSTANDING_TRANSACTION | Waiting for the app to start. |
| NO_CLIENT | (same as above) |
| USER_REQ | Not used |
| STARTED | App has started, but no eID has not been opened yet. |
UserInfo
| Attribute | Value |
|---|---|
| subjectIdentifier | Unique identifier of the subject. |
| subjectIdentifierType | Specifies subject identifier type. Currently used are: "ssn" (personnummer), "email" - user e-mail address. |
| displayName | User display name. Used by some providers for given name + surname |
| givenName | User given name |
| sn | User surname |
| ipAddress | IP address of the eID client |
ValidationInfo
| Attribute | Value |
|---|---|
| signature | Base64 encoded signature in the format specified by "signatureFormat". |
| signatureFormat | Current supported formats are: "xmldsig" - Standard XML based format used by BankID. "pkcs7" - PKCS#7, binary format used by NetID etc. "jws" - JSON Web Signature format used by Freja. |
| ocspResponse | Base64 encoded OCSP response (not available for all providers). |
GrpFault
Error during some operation results in a GrpFault being thrown. Details in the error responses may include error messages from the eID provider. GrpFault contains both a more detailed message intended for logging, and an error status type specified below.
| Error code | Information |
|---|---|
| INVALID_PARAMETERS | Could not handle request. Check input parameters. Could also be result of collect being performed more than once for some providers. |
| ACCESS_DENIED_RP | The request was not allowed for the given provider. |
| RETRY | An error occurred. RP should not automatically retry, but let user try again. |
| INTERNAL_ERROR | Internal error in GRP or eID provider system. |
| EXPIRED_TRANSACTION | The operation has timed out and user needs to retry. |
| USER_CANCEL | The operation was cancelled by the user. |
| CLIENT_ERR | An error has occurred in the client. |
| CERTIFICATE_ERR | An error with the certificate has occurred. |
| CANCELLED | The operation was cancelled because another order for the same user was added. |
| START_FAILED | The client could not be started. |
| ALREADY_IN_PROGRESS | Another operation for the same user is already in progress. That order is cancelled and no new order is created. RP needs to try again. |
| SIGN_VALIDATION_FAILED | Validation of a signature could not be validated. Also applies to the signature of an authentication operation. |
| UNKNOWN_USER | Invalid user identifier. Used for some eID providers instead of INVALID_PARAMETERS. |
Examples:
Example authentication (BankID same device)
Example authentication (BankID separate devices)
Known Bugs
| 2018-11-29 | CollectResponseType defined userInfo and validationInfo with minOccurs element but should be 0 | Scheduled for next upgrade |
|---|---|---|