Sign in customers

Sign customers into your website and grant them access to protected content.

Pliro supports signing customers into your website using the OpenID Connect Authorization Code Flow:

Here's how it works step-by-step:

Step 1: Request an authorization code

When the customer clicks the sign in button on your website you'll need to redirect them to Pliro's authorization endpoint:

HTTP/1.1 302 Found
Location: https://example-publication.plirotest.page/oauth/authorize?
  response_type=code&
  scope=openid%20email%20profile&
  client_id=example-client-id&
  redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

This endpoint requires the following query parameters:

• response_type: Must be set to code.

• scope: A space-separated list of requested scopes. Must include openid. Can optionally include email to request that the customer's email is included in ID tokens, and profile to request the inclusion of the customer's name and subscription plan. Example: openid email profile.

• client_id: Must be set to the client ID shown for your OAuth application in the Pliro dashboard.

• redirect_uri: Must be set to the redirect URI you have specified for your OAuth application in the Pliro dashboard. The provided URI can optionally include query parameters not included in the registered redirect URI.

After you have redirected the customer to this endpoint, Pliro will prompt the customer to sign in. When the customer has signed in, Pliro will redirect them to the provided redirect_uri with an authorization code in the code query parameter. For example:

HTTP/1.1 302 Found
Location: https://example.com/callback?code=example-code

The authorization endpoint also accepts the following optional parameters:

• state: Recommended. If set, a state query parameter with the same value will be added to the redirect_uri before redirecting the customer back to your website. We recommend storing this value in the customer's session in a way that can't be tampered with before redirecting them to Pliro, and then checking that the state parameter in the request to the redirect URI matches the one stored in the session. This provides CSRF protection.
• prompt: When set to none, Pliro won't prompt the customer to sign in. See the section Silent re-authentication below for more information on this.

Error handling

If the authorization request fails due to an invalid redirect_uri or client_id, the customer will not be redirected to the redirect_uri.

In case of other errors, the customer will be redirected to the redirect_ur with an error code in the error query parameter. For example:

HTTP/1.1 302 Found
Location: https://example.com/callback?error=invalid_request

Pliro can return the following error codes:

• invalid_request: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

• unauthorized_client: The client is not authorized to request an authorization code using this method.

• unsupported_response_type: The server does not support obtaining an authorization code using this method.

• invalid_scope: The requested scope is invalid, unknown, or malformed.

• server_error: The server encountered an unexpected condition that prevented it from fulfilling the request.

• login_required: The customer needs to sign in. This error is returned when the prompt parameter is set to none and the customer is currently signed out of Pliro.

Step 2: Request access and ID tokens

When your website processes the request to the redirect_uri (and has verified its authenticity using the state parameter), it can exchange the code for access and ID tokens by making a request to the token endpoint:

POST /oauth/token HTTP/1.1
Host: example-publication.plirotest.page
Content-Type: application/x-www-form-urlencoded
Authorization: Basic WU9VUl9DTElFTlRfSUQ6WU9VUl9DTElFTlRfU0VDUkVU

grant_type=authorization_code&
code=example-code&
redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

The request needs to include Basic authentication using your application's client ID as the username and client secret as the password.

The successful response includes access and ID tokens:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "example-access-token",
  "token_type": "Bearer",
  "expires_in":7200,
  "scope": "openid email profile",
  "created_at": 1679395531,
  "id_token": "example-id-token"
}

Error handling

If the token request fails, the server responds with an HTTP 400 or 401 status code and includes an error code in the response body:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
 "error": "invalid_request"
}

• invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

• invalid_client: Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).

• invalid_grant: The provided authorization grant (e.g., authorization code) is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

• unauthorized_client: The authenticated client is not authorized to use this authorization grant type.

• unsupported_grant_type: The authorization grant type is not supported by the authorization server.

Step 3: Sign the customer in and store their tokens

You can now sign the customer into your website (e.g., by setting a session cookie). You should also store the following information in their session:

• Their access token: This is required to retrieve updated customer information.
• Their id token: This is required to sign customers out of Pliro.

The ID token contains additional information, in the form of a JSON Web Token, that you may want to store separately:

• The customer's Pliro session ID (sid): This can be useful when processing sign-out notifications.
• The customer's email (if the email scope was included in the authorization request).

• The customer's name (if the profile scope was included in the authorization request).

• The slug for the plan that the customer subscribes to (if the profile scope was included in the authorization request). This can be useful when managing the customer's access to protected content.

To access this information, the ID token needs to be decoded. This can be done with one of the many existing JWT libraries. Use Pliro's signing keys when verifying the token's signature.

Step 4: Grant the customer access to protected content

Whenever the customer attempts to access a protected piece of content you can use the information stored in their session to authorize their access. At some point you may want to update this information.