Guides
Developer Portal (sandbox)Developer Portal (production)Lifen Platform status
These docs are for v2. Click to read the latest docs for v3.

Connect Users v2

Suggest Edits

Lifen's Connect API can be used for both authentication and authorization. This document describes our OAuth 2.0 implementation, which conforms to the OpenID Connect specification.

Authenticating the user

Authenticating the user involves obtaining an Access Token, which can be used to access Lifen's APIs on behalf of the user.

Lifen supports the Authorization Code flow to authenticate a user from the back-end server of an application and verify its identity through browser interaction. The Authorization Code with PKCE can be used when a client-side application (Single Page Apps, Mobile Apps or Native Apps) needs to connect users directly without a back-end server.

This document describes below how to perform the Authorization Code flow from a back-end server. For the client-side flow (PKCE), you can find implementation details in the Authorize Endpoint but we highly recommend using a client library compliant with OAuth 2.0.

Server-side flow

When a user tries to log in with Lifen, you need to :

  1. Send an Authorization request to Lifen
  2. Confirm the anti-forgery state token
  3. Exchange the code for Access Token
  4. Obtain user information
  5. Authenticate the user

1. Send an Authorization request to Lifen

You need to form a URL with the appropriate query parameters to redirect the user to the Lifen Connect authentication and authorization flow.

An example of a complete Authorization request :

https://login.lifen.fr/authorize?
    state=g6Fo2SBVQmw0cEJTTHctZmVMN1E1R&
    client_id=clientidclientidclientid&
    redirect_uri=https%3A//app.example.com/callback&
    response_type=code&
		version=2.0.0&
    scope=openid%20email

The following parameters need some attention :

  • state, a unique session token that holds state between your app and the user's client. You later match this unique session token with the authentication response returned by the Lifen Connect to verify that the user is making the request and not a malicious attacker. These tokens are often referred to as cross-site request forgery (CSRF) tokens. We recommend generating a random string of at least 30 characters.

  • client_id, which you obtain from your account manager.

  • redirect_uri is the HTTPS endpoint on your server that will receive the response from Lifen. The value must exactly match one of the Allowed Callback URLs for the OAuth App. Contact us to add a new Callback URL.

  • scope allows you to request specific user permissions separated by a whitespace to access Lifen's APIs on his behalf (read Access permissions for details).

See the Server-side User flow (Authorization Code grant) for more details about all the parameters.

2. Confirm the anti-forgery state token

After the user authorized your application, Lifen redirects back the user to your redirect_uri with a short living code and the state you provided as parameters.

You must confirm on the server-side that the state received from Lifen matches the unique session token you created and sent in the authorization request before. This round-trip verification helps to ensure that the user, not a malicious script, is making the request.

3. Exchange the code for Access Token

You can now exchange the code received from Lifen for an Access Token, and an ID Token if you requested the openid scope.

An example of a complete Exchange code request :

curl --request POST \
  --url 'https://login.lifen.fr/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'client_id=clientidclientidclientid' \
  --data 'client_secret=clientsecretclientsecret' \
  --data 'code=-5GyxALXWWMPbhsl' \
  --data 'redirect_uri=https%3A//app.example.com/callback'

The following parameters need some attention :

  • code, the authorization code received in the callback with the state.
  • redirect_uri, the value must matches the redirect_uri you sent in the Authorization request

Warning: Only use client_secret on the server-side. If you want to authenticate users from a frontend (Single Page App, Native App, or Mobile App), take a look at the Authorization Code with PKCE in the Authorization Code Flow with PKCE.

You will get an HTTP 200 response with a payload containing access_token, expires_in, token_type and optionally id_token.

{
    "access_token": "eyJ...Y7p9g",
		"id_token": "eyJ...Os32d",
    "expires_in": 172800,
    "token_type": "Bearer"
}
  • Access tokens are used to access authorized user data on Lifen API.
  • ID tokens contain user information that can be validated and decoded within your application.

4. Obtain user information

The ID token is a JWT that can be decoded and allows you to read basic user information within your application without additional API calls.

Example of an ID token's payload with the email and profile scopes :

{
    "http://lifen.fr/applicationName": "Lifen Demo",
    "http://lifen.fr/userInfo": {
        "uuid": "2239c4e4-f928-44da-917d-1a59a7a4e931",
        "apiUrl": "https://fhir-api.lifen.fr",
        "currentWorkspaceId": "Organization/6944011",
        "identities": [
            "Practitioner/319035",
            "Practitioner/62410"
        ]
    },
    "nickname": "victor.pugin",
    "name": "Victor Pugin",
    "picture": "https://s.gravatar.com/avatar/db7a45895d282c86badc8115694dc67f?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fvi.png",
    "updated_at": "2021-02-04T13:41:24.235Z",
    "email": "[email protected]",
    "email_verified": true,
    "iss": "https://login.lifen.fr/",
    "sub": "auth0|[email protected]",
    "aud": "i1OU7pVVP3e1Qbux1Lvcf9fuRGt36bnq",
    "iat": 1612521016,
    "exp": 1612607416,
    "at_hash": "H2uHnFQp-hf6hXEztwraTg",
    "nonce": "t54Y78j_m91haC1_tOfZD9qxeLrVlZpe"
}

The following user information are the most useful :

  • http://lifen.fr/userInfo.uuid: a unique Lifen User ID
  • name: the user's full name
  • email: the user's email address

Since you are communicating directly with Lifen, you can be confident that the token you received really comes from us and is valid. But if your server passes the ID token to other components of your app, the other components must validate the token before using it.

We recommend using a library able to verify and decode properly JWTs for you. If you don't want to handle ID tokens, you can remotely fetch user information.

Remotely fetch user information

With the cost of an additional HTTP call, you can avoid the complexity of decoding and validating the ID token yourself to read user information.

It's the easy way recommended for a quick start, but not for long-term production.

You just need to do a /userinfo call with the Access Token in the Auhthorization header :

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://login.lifen.fr/userinfo

The Connect API checks the validity of the Access Token, then returns the user information.

5. Authenticate the user

After obtaining user information, you can query your app's users' database. If the user already exists in your database, you should start an application session.

If the user does not exist in your users' database, you should redirect the user to your sign-up flow. You may be able to auto-register the user based on the information you receive from Lifen, or at the very least you may be able to pre-populate many of the fields that you require on your registration form.

We recommend linking your app's users' database to Lifen User IDs because users' emails may change.

Call Lifen APIs with user's access token

The Access Token allows you to make requests to the API on the behalf of the authenticated user. Each request must include the Access Token in the Authorization header using the Bearer format.

Example :

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://api.lifen.fr/$endpoint

Updated about 2 years ago