Single Sign On Particeep (SSO) procedure

We use the Macaroons principle to manage our SSO connection.

Macaroon: definition

Like Cookies, Macaroons are tokens that carry the user's identity. Their main advantages are:

• Delegation: you can delegate a badge to another entity. By the way, you can restrict the rights associated with the token.
• Integrated rules: a badge has its own validation rules. You can easily add a constraint to a badge, but you cannot remove one without breaking the cryptographic validation.
• Simple validation: a badge can be validated very easily without calling on a remote server.

These advantages make buttons very effective for decentralized authentication: once the token is created any system can verify it using a shared secret. The absence of a central server eliminates the Single Point Of Failure of some SSO systems.

The name "macaroon" makes google searches a bit "complicated", we advise you to read the links in the reference section to familiarize yourself with macaroons.

There are implementations in all major languages (C, Java, Python, Go, Php, etc ...)

Particeep Protocol

General concept

To switch from one application to another, we will associate a macaroon token with the request. The application that receives this token can decrypt it using a share secret and automatically log in the user.

The process is the same in both directions:

• From the Particeep backoffice and user interfaces to an external application
• From an external application to the Particeep backoffice

Particeep SSO does not allow you to create a user: the user must be created beforehand on the Particeep platform.

Token Format

The token has 2 distinct parts:

A login

The identifier is a String which encodes parameters allowing the user to be identified. It is of the following form:

• token_name=$token_name:email=$email:user_id=$user_id
• token_name: is an environment variable. It takes the following values

• Test environment: Particeep_M_Token_Test
• Production environment: Particeep_M_Token
• email: the email that the user uses to connect to the Particeep platform
• user_id: the id of the user on the Particeep platform. This parameter is optional

Examples:

In the test environment for the user admin@particeep.com which has id 6f92033a-5efe-46ba-a442-dc8abdddee50 you can build the following credentials

token_name=Particeep_M_Token_Test:email=admin@particeep.com:user_id=6f92033a-5efe-46ba-a442-dc8abdddee50

token_name=Particeep_M_Token_Test:email=admin@particeep.com

Caveats

Caveats are the token validation rules.

We apply the following rules as first_party_caveat:

• ip: contains the user's ip
• browser: contains the user-agent of the user's current browser
• time <yyyy-MM-ddThh:mm: indicates the expiration time of the token. Particeep applications create tokens valid for 24 hours
• api_keys: contains the API key
• authorities: contains the role of the user. For CGP, must contain PARTNER _ ${api key}
• For admin and sub-admin, must contain ADMIN _ ${api key}

When you receive a token you must check these rules.

When you create a token you must register these rules on the token.

Finally, the token is signed with your API secret

We strongly recommend that you use an official macaron implementation to create or read a token. The implementation documentation will tell you how to add and verify caveats. There is an example in Java at the end of the document.

Token transport

In an SSO with different DNS domains, the use case is a GET type redirection between the 2 applications. The token is therefore passed as a URL parameter.

we are looking for a parameter named $token_name

This is the same parameter as in the identifier. It takes the following values.

• test environment: Particeep_M_Token_Test
• production environment: Particeep_M_Token

The target URL must be an application page, not a satellite page.

A page of the backoffice application has a URL of this form.

• test environment: [urlapp]/${api_key}/.*
• production environment: [urlapp]/${api_key}/.*

All other pages are doorway pages.

Example: