Page tree
Skip to end of metadata
Go to start of metadata

OAuth2.0 Autorizācijas API

The OAuth 2.0 authorization model allows a Service provider's application to obtain access to a HTTP service or resource, either on behalf of the end-user who owns the resource or on behalf of the Service provider's application itself. To do this, the Service provider's application obtains an access token via the following operations:

API authorization code request.

API access token request.

Autorizācijas koda saņemšana

Description

This operation entails performing an authorization code grant type OAuth 2.0 request request.  In contrast to the other Integration platform APIs (except SignAPI), the messages of this operation are not exchanged directly between the Service provider's application and Integration platform but rather indirectly via the end-user's browser using browser redirects.

This operation lets an Service provider's application obtain authorization from the end-user for accessing one of their resources or their identity data. The end-user's authorization is obtained via an authorization code credential. The authorization code is sent via the browser as a response from the operation. The Service provider's application exchanges the authorization code for the corresponding access token for accessing the resource.

Request

To start the authorization code grant flow, the Service provider's application directs the end-user's browser to one of Authorization server /trustedx-authserver/oauth/ endpoints. As a result of this redirect, the browser sends an HTTP request like the following, which corresponds to the OAuth 2.0 authorization request message. The request must be sent by TLS and use the GET method.

GET /trustedx-authserver/oauth/{as}?response_type=code&
             client_id=...& 
             state=...&
             redirect_uri=...&
             scope=...&
             prompt=...&
             acr_values=...&
             ui_locales=...&
             sign_identity_id = ...&
             digests_summary = ...&
             digests_summary_algorithm = ...&   
Note
All the applications integrated with Integration platform authorization server via browser redirect (OAuth 2.0) must do so using a consistent base URL that has the same DNS domain name, the same port (by default, 8082) and the same Web application name (by default, trustedx-authserver). The browsers must always connect to Integration platform Authorization server using the same base address so the identity provider can maintain the sessions and apply SSO consistently.

Parameters


Name

Type

Usage

Description

as

Path

Required

Identifier of the Integration platform authorization server to which the authorization request is sent (Server ID field of one of the Authorization server entities).

Available "as" (will be specified when issuing client_id and client_secret after registration):

lvrtc-eips-as

lvrtc-eipsign-as

response_type

Query

Required

Must take the code value, which indicates that an authorization code is requested.

client_id

Query

Required

Service provider’s application identifier issued to Service provider by LVRTC

state

Query

Recommended

We recommend using this parameter to safeguard against CSRF attacks. To do this, the Service provider’s application must include a random value in this parameter, store it in the HTTP session and verify it when the Authorization Response message is received. The random value associates the authorization request with the HTTP session, which safeguards against the Service provider’s application processing an Authorization Response message not returned in response to an Authorization Request message specified previously in the end-user's browser.

redirect_uri

Query

Required

Redirect URI to the Service provider's application. The Service provider's application waits to receive at this URI the Authorization response/Authentication response message with the authorization code. It must match one of the Redirect URIs registered for the Service provider's application, or a redirect URI of the system. If the Service provider's application was configured to allow any redirect URI (not recommended), this parameter is not checked.

This parameter can be omitted if only one specific redirect URI was registered for the Service provider's application. In this case, the registered redirect URI is used.

scope

Query

Recommended

List of values, separated by spaces, that represent the scope of the authorization that the Service provider’s application wants to obtain. It queries the scopes required for accessing the resources or services in question.

Defined scopes:

urn:lvrtc:fpeil:aa – For electronic identification

urn:lvrtc:fpeil:aa:age – For electronic identification with age parameter (Restricted access, contact LVRTC for more information.)

urn:safelayer:eidas:sign:identity:profile – to get signing identity

urn:safelayer:eidas:sign:identity:use:server – to request signature from the HSM.

urn:safelayer:eidas:oauth:token:introspect – For access LVRTC provided Integration platform SignAPI service (Service provider authentication (without end-user involvement)).

prompt

Query

Recommended

The values login and none are supported:

  • The login value disables SSO, a login page is displayed (redirect) always.

  • The none value specifies that there can be no interaction with the end-user (neither for authenticating them nor for requesting their authorization).

acr_values

Query

Optional

Defines conditions for authenticating the end-user (minimum levels or specific flows) who must authorize the access.

Defined authentication methods:

  • urn:eparaksts:authentication:flow:mobileid - eParaksts mobile flow;
  • urn:eparaksts:authentication:flow:sc_plugin – Smart card flow;

If the parameter is not specified, its displays the available logon methods (end-user can choose).

ui_locales

Query

Optional

Specifies a list of languages ordered by preference. The end-user interface, available languages and settings:

  • lv – Latvian language;
  • en – English language;
  • ru – Russian language;

If the parameter is not specified, a end-user's browser language is used, if that language does not exist, then English language is used instead.

sign_identity_id

Query

Optional

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM. (warning)

Signing Identity received from authenticated end-user data request using urn:safelayer:eidas:sign:identity:profile scope (serverid label).

digests_summary

Query

Optional

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM.(warning)

Its value must be the base64 encoded cryptographic hash of the concatenation of the cryptographic hashes of the data to be digitally signed.

Value must be encoded as URL safe.

(warning)(warning)(warning) Very important! Hash value shall be recalculated with digests_summary_algorithm from signable data value, e.g. BASE64(SHA256(<signable data>))(warning)(warning)(warning)

digests_summary_algorithm

Query

Optional

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM.(warning)

Hash algorithm used to calculate digests_summary value (SHA256 for example)


Note
Don’t confuse the HTTP session that the application has with the browser with the security context or session the application creates or updates when the OAuth 2.0 flow finishes. The HTTP session exists previously, from the moment the browser accesses the Web application, and even though the end-user has not already authenticated. The security context is data on the authenticated end-user that the application usually stores in the HTTP session to remember that it is this end-user that is logged in to the application via the browser, and/or the OAuth access token. Just as the application does, TrustedX also keeps an HTTP session with the browser and a security context for the authenticated end-user.

Example: Authorization Request

This example shows an OAuth 2.0 authorization request message from the "Portal". The Service provider’s application requests an authorization with the "urn:lvrtc:fpeil:aa" scope to authorization server "lvrtc-eips-as" with condition the login page is displayed in the Latvian language.

GET /trustedx-authserver/oauth/lvrtc-eips-as?response_type=code&
                                   client_id=port%C4%81ls&
                                   state=1234567890&
                                   redirect_uri=https%3A%2F%2Fwww.demoapp.lv%2Foauth%2Fback&
                                   scope=urn%3Alvrtc%3Afpeil%3Aaa&
                                   prompt=login& ui_locales=lv HTTP/1.1
Host: eidas.eparaksts.lv

Example: Signature Authorization Request

Additional parameters to end-user authentication must be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM (On signing procedure Server signing checks whatever signable data to be signed conform to data provided for signing).

If end-user is already authenticated with active SSO, end-user will have to enter signing (HSM) password only.

GET /trustedx-authserver/oauth/{as}?response_type=code&
           client_id=...&
           state=...&
           redirect_uri=...&
           scope=...&
           prompt=...&
           acr_values=...&
           ui_locales=...&  
           sign_identity_id=...&
           digests_summary_algorithm=...&
           digests_summary=...

Response

Once the end-user has been authenticated (or SSO applied), and the end-user has granted authorization, the Service provider’s application receives an HTTP GET request of the following type from the end-user's browser. This HTTP request is an OAuth 2.0 authorization response or an OpenID Connect authentication response. The Service provider’s application receives this request at the redirect URL specified in the authorization or authentication request message (the redirect_uri parameter of the request) or in the registered redirect URL.

GET {redirection_uri_path}?code={code}&state={state} HTTP/1.1
Host: {redirection_uri_host}


Where {redirection_uri_host}{redirection_uri_path} is the redirect URI to the Service provider’s application.


Piekļuves talona(token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 authorization code grant flow or via an OAuth 2.0 Service provider's credentials grant flow.

End-user access token

When the authorization code grant flow is used, the obtained access token represents the authorization granted by a end-user to the Service provider's application making the call for accessing certain resources or services on this end-user's behalf (identity data, signature identities, etc.). To obtain the token, the Service provider's application must present the authorization code obtained with the Obtain authorization operation.

This type access token is used to receive end-user's:

  • Electronic identification;
  • signing identities;
  • eParaksts Mobile related signing and authentication certificates;
  • PKSC#1 signature

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Identifier of the authorization server from which the token is requested

available "as":


Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

Body

The content of the request varies according to the type of OAuth 2.0 flow in which the token is requested:

Content in the Case of the Authorization Code Grant Flow (used for electronic identification/signing requests)

Property

Usage

Description

grant_type

mandatory

Must have the authorization_code value.

code

mandatory

The authorization code received in the previous authorization response.

redirect_uri

mandatory

URI where the authorization response was received with the authorization code. Must match the redirect_uri parameter of the API authorization code request (see API authorization code request), and must be omitted if it is also omitted in the authorization request.

Content in the Case of the Client Credentials Grant Flow - Introspect access token (used for access SignAPI service)

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Introspect access token

 Introspect access token explained...

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

 API Access Key basics...

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example (end-users access token)

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Host: eidas-demo.eparaksts.lv
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
 
grant_type=authorization_code&
   redirect_uri=https%3A%2F%2Fwww.portals.lv%2Foauth%2Fback&
   code=4515...e0ba

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Access token with end-user authentication:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
"access_token" : "a2b4...6daf",
"token_type" : "Bearer", 
"expires_in" : 120
}

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



  • No labels