Security

Security

The EUIPO’s APIs use the OpenID Connect (OIDC) protocol for user authentication and application authorisation. OpenID Connect is an open authentication protocol that profiles and extends OAuth 2.0, an authorisation framework, to add an identity layer. OIDC allows clients to confirm an end user’s identity using authentication by an authorisation server.

An OAuth 2.0 server issues access tokens that client applications can use to access protected resources on behalf of the resource owner, (e.g.: create an EUTM Application on behalf of the user).

Before performing any operation with APIs, you need to obtain an authorisation token. OAuth2.0 provides various flows or grant types suitable for different types of API clients or use cases.

Some APIs may require identifying the application and the final user while the requirements of others will only be satisfied by uniquely identifying the application.

The EUIPO’s APIs that belong to the first group will specify ‘accessCode’ security flow in their security requirements ...

 

while APIs of the latter group will specify the ‘clientCredentials’ security flow.

 

However, the authorisation mechanism also allows fine grain authorisations. For instance, the user may authorise an application to apply for trade mark registrations but not design registrations. This is possible thanks to scopes.

Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s resources.

Operations in API definitions include the required scopes in each case.

Example of EUTM Filing API where scope ‘eutm-filing.application.write’ is required to submit a new application

 

Identifying only the application: Application flow

 

Example of Trademark Seach API

 

You can use this security flow if the API you’re consuming does not need to know the information of the final user. An example of a request to get an Access Token using curl could be the following:

curl --location --request POST ‘https://auth-sandbox.euipo.europa.eu/oidc/accessToken’ \
                      --header ‘Content-Type: application/x-www-form-urlencoded’ \
                      --data-urlencode ‘client_id=<YOUR_CLIENT_ID>‘ \
                      --data-urlencode ‘client_secret=<YOUR_CLIENT_SECRET>‘ \
                      --data-urlencode ‘grant_type=client_credentials’
                      --data-urlencode ‘scope=uid’

 

The response should be as follows:

{
                      ‘access_token’: ‘eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiVGVzdCIsIklzc3VlciI6Iklzc3VlciIsIlVzZXJuYW1lIjoiVGVzdCIsImV4cCI6MTY2OTk4MTQ1MCwiaWF0IjoxNjY5OTgxNDUwfQ._80PYR1ZX6eOPVFgtdpQNOu6vKaKVd97VI-KVAS9EhI’,
                      ‘id_token’: ‘eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiVGVzdDIiLCJJc3N1ZXIiOiJJc3N1ZXIiLCJVc2VybmFtZSI6IlRlc3QyIiwiZXhwIjoxNjY5OTgxNDUwLCJpYXQiOjE2Njk5ODE0NTB9.VvkNnz0HatlYl3qwayYLs3p8PPkGM3C1KArn28DmMCE’,
                      ‘refresh_token’: ‘RT-2022-Q2pShv8cnKEmHarxTIdW-8OqJSg7rGLG’,
                      ‘token_type’: ‘bearer’,
                      ‘expires_in’: 28800,
                      ‘scope’: ‘uid’
                      }

 

Identifying application and final user - Access Code

 

Example of EUTM Filing API

With the ‘access code’ authorisation flow, the final user never provides her credentials to the application. The application opens a browser to redirect the user to the OAuth server. The user sees the authorisation form and approves the application’s request. The user is redirected back to the application with an authorisation code that is used later by the application to ask for the access token to the authorisation server.

Step 1: Get Authorisation Code

The user needs to authorise the application to act on her behalf: At this point, the browser is redirected to the authorisation form of the Authorisation Server using an URL similar to this one :

https://auth-sandbox.euipo.europa.eu/oidc/authorize?response_type=code&client_id=&redirect_uri=&scope=

NOTE: Please note that YOUR_APP_CALLBACK corresponds with the value that you configured in OAuth Redirect URI when you registered your application in the API Portal.

 

The authorisation server presents the Authorisation form from where the final user authorises the application.

 

Once the user does the log in using her credentials, the browser is redirected to ‘YOUR_APP_CALLBACK’ URL including the authorisation code as a parameter:

 

Step 2: Get Access Token

Now the application can ask for the access token using the returned code as it is shown in the following example:

curl --location --request POST ‘https://auth-sandbox.euipo.europa.eu/oidc/accessToken’ \
                      --header ‘Content-Type: application/x-www-form-urlencoded’ \
                      --data-urlencode ‘client_id=<YOUR_CLIENT_ID>‘ \
                      --data-urlencode ‘client_secret=<YOUR_CLIENT_SECRET>‘ \
                      --data-urlencode ‘code=<AUTHORIZATION_CODE>‘ \
                      --data-urlencode ‘grant_type=authorization_code’ \
                      --data-urlencode ‘redirect_uri=<YOUR_APP_CALLBACK>‘

 

Refresh token

For security reasons, access tokens have an expiration time. If the application needs to refresh the token before it expires, it should do so using a request like the following:

curl --location --request POST ‘https://auth-sandbox.euipo.europa.eu/oidc/accessToken’ \
                      --header ‘Content-Type: application/x-www-form-urlencoded’ \
                      --data-urlencode ‘refresh_token=<YOUR_REFRESH_TOKEN>‘ \
                      --data-urlencode ‘grant_type=refresh_token’ \
                      --data-urlencode ‘client_id=<YOUR_CLIENT_ID>‘ \
                      --data-urlencode ‘client_secret=<YOUR_CLIENT_SECRET>‘


This is especially interesting when the application uses the ‘Access code’ security flow that requires that the user interact to authorise the application to act on her behalf. Refreshing a token does not require a new user authorisation. The application simply asks the authorisation server to extend the duration of the current token.

In any case, the application could always ask for a new access token if it fits better with its use case.

 

Common errors

Authorisation server shows an error screen when my App tries to open the authorise form as part of the ‘access_code’ flow.

 

It usually happens when the ‘clientId’ or the ‘redirect_uri’ used in the ‘authorise URL’ are incorrect:

https://auth-sandbox.euipo.europa.eu/oidc/authorize?response_type=code&client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_APP_CALLBACK>&scope=<SCOPE_LIST_SEPARATED_BY_SPACES>&redirect_uri=&scope=

Please check your App configuration in the API Portal.

 

Authorisation server responds with 401 when my App requests the access token

Your App is using an incorrect clientId or clientSecret. Please check your App configuration in the API Portal.

{
                        ‘timestamp’: ’2023-07-25T10:13:00.327+00:00’,
                        ‘status’: 401,
                        ‘error’: ’Unauthorized’,
                        ‘message’: ’’,
                        ‘path’: ’/oidc/accessToken’
                      }

 

API gateway responds with 401 when my App calls to an API operation

Several reasons may be behind this error:

Your App request might be using an incorrect ‘clientId’ or it could be completely omitted from headers.

{
                        ‘httpCode’: ’401’,
                        ‘httpMessage’: ’Unauthorized’,
                        ‘moreInformation’: ’Invalid client id or secret.’
                      }

 

Your App didn’t include the Authorisation header with the access token as part of the request, or it expired. In this scenario, the API gateway will respond with the following error:

{
                        ‘httpCode’: ’401’,
                        ‘httpMessage’: ’Unauthorized’,
                        ‘moreInformation’: ’Cannot pass the security checks that are required by the target API or operation, Enable debug headers for more details.’
                      }

 

The requested operation required some mandatory scopes that were not included in the access token. Please check API documentation.

{
                        ‘httpCode’: ’401’,
                        ‘httpMessage’: ’Unauthorized’,
                        ‘moreInformation’: ’Cannot pass the security checks that are required by the target API or operation, Enable debug headers for more details.’
                      }

 

API gateway responds with 403 when my App calls to an API operation

Several reasons may be behind this error:

Your App is not registered to one of the plans offered by this API Product. Please check your subscriptions.

{
                        ‘httpCode’: ’403’,
                        ‘httpMessage’: ’Forbidden’,
                        ‘moreInformation’: ’Not registered to plan.’
                      }

 

This API operation required the ‘access_code’ flow and your App used ‘client_credentials’, so the identity of the final user is not available in the access token. Please check the API documentation.

{
                        ‘type’: ’/problems/access-forbidden’,
                        ‘title’: ’Access forbidden’,
                        ‘detail’: ’Access is denied’,
                        ‘status’: 403,
                        ‘instance’: ’/applications’
                      }