Sign in members

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

Pliro supports signing members 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 member 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 member's email is included in ID tokens, and profile to request the inclusion of the member'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 member to this endpoint, Pliro will prompt the member to sign in. When the member 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 member back to your website. We recommend storing this value in the member'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 member 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 member will not be redirected to the redirect_uri.

In case of other errors, the member 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 member needs to sign in. This error is returned when the prompt parameter is set to none and the member 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 member in and store their tokens

You can now sign the member 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 member information.

• Their id token: This is required to sign members 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 member's Pliro session ID (sid): This can be useful when processing sign-out notifications.

• The member's email (if the email scope was included in the authorization request).

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

• The slug for the plan that the member subscribes to (if the profile scope was included in the authorization request). This can be useful when managing the member'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 member access to protected content

Whenever the member 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.