Adding an Yle Tunnus login to your site

Yle Login allows users to create accounts and sign in to your website and apps securely and with minimal friction.

Obtaining Yle Tunnus client credentials

To get started, you must first obtain Yle Tunnus client credentials, a token verification key, and Yle API credentials for your application. You can request these from Yle API team (via the contact form), or they may have been delivered to you by some other agreement.

Before requesting for credentials, be sure that you have the following information ready:

1. What type of authorization scenario needs to be set up for you?

This depends on your application. The options are either server-side authorization (if your application is a typical web server application) or client-side authorization (if your application is a client-side JavaScript application that runs on a browser).

2. What are the scopes (permissions) that your application supports, and that require authorization from your users?

At the bare minimum your application may only need the default sub scope, which provides you with an unique identifier of the user and nothing else.

3. What is the redirect URI (or multiple such URIs) that Yle Tunnus authorization servers use to redirect back to your site?

This URI should provide an endpoint that is capable of accepting OAuth 2.0 authorization responses. It is strongly recommended that this endpoint is secured with HTTPS.

Making authorization requests

After you have obtained the credentials, you are ready to try out some authorization requests. Yle Tunnus implements the most common authorization flows of OAuth 2.0 protocol (server-side authorization grant, and client-side implicit grant).

Authorization process in a nutshell

Typical authorization process with Yle Tunnus goes as follows:

  1. User attempts an operation that requires authorization on your site. You have added an option for users to provide authorization with Yle Tunnus on your site, following Yle Tunnus login UI guidelines.
  2. Authorization request is sent to Yle Tunnus authorization server from your site.
  3. User authenticates his/herself, if needed.
  4. User is asked to grant the permissions that your application is requesting. User does so (or chooses not to, in which case the process is aborted and user is redirected back to your site).

  5. At this step, the authorization grant and implicit grant flows differ slightly:

    a) In the authorization grant flow, Yle Tunnus authorization server sends an authorization token back to your application. Your application then makes an additional request (server-side) with the authorization code and receives an access token.

    b) In the implicit grant flow, Yle Tunnus authorization server sends an access token back to your application immediately, and no additional request is needed.

  6. Your application can now use the access token to authenticate and authorize user’s operations.

Authorization grant flow

This example covers the authorization grant flow, which starts with a request for an authorization code.

Here is a blueprint of such request:

GET https://auth.api.yle.fi/v1/authorize?
  response_type=code&
  client_id=<your client id>&
  app_id=<your app id>&
  app_key=<your app key>&
  redirect_uri=<your redirect URI>&
  scope=<your requested scope>&
  state=<state>

The following parameters will need to be filled in with appropriate values. (Please note that your client secret must not be included in this request.)

Parameter Description
client_id Your Yle Tunnus client id.
app_id Your Yle API app id.
app_key Your Yle API app key.
redirect_uri Your redirect URI. This must match the redirect URI that has been configured for your application. This is the address where the authorization response is sent to.
scope The requested scope(s), delimited by spaces. This must only contain scopes that have been configured for your application.
state A string that represents the state of your application at the time of the request. This value is returned to your application in the response, so it can also be used to protect against cross-site request forgeries. The values should be rather unique. Be careful to not leak out sensitive information!

After receiving such request, Yle Tunnus authorization server proceeds to authenticate the user (if necessary), and obtain consent from the user for the requested scope(s). Then, the response is sent back to your application’s redirect URI. When successful, this response will contain an authorization code, and the state that you included in the request (unchanged).

Remember to also make sure that your application handles possible error codes from Yle Tunnus authorization server gracefully, so that the user experience will always remain pleasant (for example, when the user aborts the authorization process for some reason).

Requesting an access token with an authorization code

Let’s see how to use the authorization code to request an actual access token:

POST https://auth.api.yle.fi/v1/token?app_id=<your app id>&app_key=<your app key>

  grant_type=authorization_code&
  client_id=<your client id>&
  client_secret=<your client secret>&
  redirect_uri=<your redirect URI>&
  code=<your authorization code>

As this one is an HTTP POST request, the parameters must be sent using application/x-www-form-urlencoded content-type. The app_id and app_key parameters remains as URL parameters.

The parameter values need to be filled in just as in the first request, in addition to these two that were not present in the first request:

Parameter Description
client_secret Your Yle Tunnus client secret.
code The authorization code that you received in the previous request’s response.

Assuming everything went smoothly, you should have received an access token in the response. The token is a JWT token that has been Base64-encoded and signed with a cryptographical key. You can validate the token by sending it to /tokeninfo endpoint of Yle Tunnus authorization server:

GET https://auth.api.yle.fi/v1/tokeninfo?
  app_id=<your app id>&
  app_key=<your app key>&
  access_token=<your access token>

If you get a 200 OK response, the token is valid.

Example response body:

{
  "access_token": "eyJhbGciOiJIUzI1NiI..."
  "expires_in": 3600
  "user_key": "5742cb90e4b038ade21587e2"
  "client_id": "your_client_id"
  "scope": "sub email"
}

Validating the token is especially important if you pass this token around in your application - other components should not automatically assume that any token passed to them is valid.

Here is an example of the payload of a valid JWT token, and a description of its fields (known as claims):

{
  "aud": "f82hf3dv",
  "iss": "https://auth.api.yle.fi",
  "sub": "56e1423bc95162266a5e2469",
  "exp": 1457607854,
  "iat": 1457604254,
  "scopes": "sub"
}
Field Description
aud Audience the token is created for. This is always the client id of your application. Your application should not accept tokens with other values.
iss Issuer of the token. This is always https://auth.api.yle.fi for Yle Tunnus JWTs.
sub Unique, non-changing identifier of the user. You can use this value in your application to identify the user.
email Email address of the user. This may change over time. It should not be used as a primary key. This value is only included if the requested scope included the string email.
exp Expiration time of the token in Unix time.
iat Issued at time of the token in Unix time.
scopes List of scopes the token was issued with.

Now you have the required information about the user at your disposal!

Implicit grant flow

Here is an example that covers the implicit grant flow. It is a bit more straightforward, as only one request is needed to receive an access token:

GET https://auth.api.yle.fi/v1/authorize?
  response_type=token&
  client_id=<your client id>&
  app_id=<your app id>&
  app_key=<your app key>&
  redirect_uri=<your redirect URI>&
  scope=<your requested scope>&
  state=<state>

Because a client-side application cannot keep the client secret hidden, it is not used in this scenario.

As a result of such request, you should be redirected to your redirect URI, with the Base64-encoded access token included in the URL fragment (along with the state value you sent, unchanged). Your application should then use a client-side script (examples can be easily found from the web) to parse the fragment.

After parsing the token, you can use it just as in the previous example. See above for an explanation of the token contents. You can also similarly use the /tokeninfo endpoint for token validation.

Removing user’s personal data

Yle Tunnus users can choose to remove their accounts. We also remove accounts in case they have been inactive for a long period. When an account is removed, and you have stored the user’s Yle Tunnus identifier, email address, or other personal data in your system, that data needs to be removed as well (without undue delay). To enable this, Yle provides the following endpoint for requesting IDs of removed users between a given start and end time:

GET https://auth.api.yle.fi/v1/subjects/removed?start_time=2019-01-01T10:00:00Z&end_time=2019-01-01T15:05:00Z&client_id=<your client id>&app_id=<your app id>&app_key=<your app id>

Header: "Content-type = application/json;charset=utf-8"

Body:
{
    "removed_user_ids": [
        "5c2a60104cedfd00013e2190",
        "575ac0e9e4b066750913e72e"
    ]
}

The start_time, end_time and client_id are all mandatory parameters. The timestamps (start_time, end_time) must conform to the full ISO 8601 format. The start_time and end_time must be no more than 30 days apart, and start_time must occur before end_time.

The protocol used must be HTTPS. The response body contains a JSON object with the identifiers of removed Yle Tunnus users in removed_user_ids array.

The endpoint should be polled regularly and all removed users should be removed from your service as well.