OpenID Integration

Direct integration with PiPA using a 3rd-party OpenID library is possible, although not wholly recommended at this time as the entire breadth of the OpenID Specification is not currently supported by PiPA but rather a tested and secure subset. However, if the language or platform used is not explicitly supported already, contact us and we may be able to supply a customized library, or at least provide explicit guidance and support for the integration.

Code flow

The most secure flow for authentication is the so-called code flow, in which a server initiates and receives response on behalf of the users and is responsible for securing communcaton on their end. There are three steps to this process:

Redirect to Authorization endpoint

The first step is to initiate the authorization process. This is done by redirecting (or openining a new window) to the PiPA Authorization endpoint at https://pipa.co/auth/authorize. There are some optional and some required parameters:

• state: string of any format which will be sent back with the access code; used to verify that the request was not intecepted. Save using a session token or some other temporary server-side storage
• scope: the permissions/information you are requesting. A full listing will be made available upon request, but 'openid' is recommended, and possibly 'email'.
• response_type: must be 'code' for this flow
• redirect_uri: the same redirect URI as specified in OpenID integration. May include additional query paremeters
• client_id: id found in console
• nonce (optional, unless specify openid scope): a randomly generated code which will be returned back with

At this point, PiPA takes over and handles the user authorization. Once the user has authorized, the page will redirect back to the specified redirect url.

Redirect URL

The second step is to receive a redirect to the redirect uri specified in the last step. This redirect will include two pieces of information:

• state: the same string as in the last step. If it doesn't match, reject this authorization step as it is likely the request was intercepted.
• code: the authorization code which allows the requesting of the tokens in the next step

Tokens

The third step is to request tokens from the PiPA server using the code that was sent in the last step. This should be a post to the token endpoint at https://pipa.co/auth/token.

• client_id: id found in console
• client_secret: secret found in cosole (remember, don't save this in source code)
• code: the code parameter from the last step
• grant_type: must be 'authorization_code'

This will result in an set of tokens 'access token' being returned to you, which contains a few things:

• access token: a relatively short-lived token used for authenticated requests against our servers
• refresh token: a token used for requesting addtional access tokens
• user id: the user id specific to this user and your integration (other companies will receive a different identifier for the same user)
• id token (if requested openid scope): a token conforming to the OpenID spec including some basic information if requested in other scopes (i.e. email)

Your website should use an existing mechanism such as cookies to retain track authentication state of the user, and re-request authentication from PiPA as needed.

Requesting Email adddress from Users

If your login system relies on email addresses, or you want to support switching to a password-based authentication scheme at a later point, you can request an email address from your users. If you request the email and the user chooses to send one, it will be contained in the OpenID token returned by the token endpoint.