Authentication with PeerID

1. Introduction

This guide describes how to use PeerID to enable your application to perform operations on behalf of a Peerplays account. The preferred method of authentication is OAuth. We use parts of the OAuth 2.0 protocol.

PeerID also allows your users to register and login to their Peerplays accounts using their Facebook, Google, and Discord accounts. PeerID uses their respective authentication to verify the user and log them into their Peerplays account.

PeerID doesn’t store passwords or keys anywhere. It uses the custom permissions on the Peerplays blockchain to perform the operations on behalf of the user.

Authentication involves:

1. Registering your app to obtain a client ID and client secret. This includes specifying scopes (permissions) your app requires.

2. Getting an access token for the PeerID user. This includes the user authorizing your app using their login credentials.

3. Sending the token in your API request to perform an operation on the Peerplays blockchain on behalf of the user.

2. Registration

To make an application that uses the PeerID API, you first need to register your application on the PeerID site. When creating your app, enter your domains, to which your users are redirected after being authorized. You can provide several domains, for example, if you wish to use the same client for different environments.

Once you create a developer application, you are assigned a client ID. Some authentication flows also require a client secret, which you can view on the same page as the client ID.

• Client IDs are public and can be shared (for example, embedded in the source of a Web page).

• Client secrets are equivalent to a password for your application and must be kept confidential.

Never expose the client secret to users, even in an obscured form!

3. Getting Tokens

PeerID supports several authentication flows: 1. OAuth Authorization code flow: This should be used when your application uses a client-server architecture, can securely store a client secret, can request the user to allow the app to perform some operations on behalf of the user, and can make server-to-server requests. This is the recommended approach. 2. OAuth Resource Owner Password Credentials flow: This should be used when your application is a single page browser app using a client-server architecture and can ask the client for credentials but you don't want the client to divert from your page.

The client credentials should never be stored in your database.

OAuth Authorization code flow Follow the below steps to get the access token for the user using the OAuth Authorization code flow:

1. Send the user you want to authenticate to your registered redirect URI. An authorization page will ask the user to sign up or log into PeerID and allow the user to choose whether to authorize your application/identity system.

Create a <a href="">login</a>:

GET https://peerid.peerplays.download/permissions  
?client_id=<your client ID>  
&redirect_uri=<URI with your registered domain>

You can also pass an optional state parameter of string type. This can be a unique token generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

1. If the user authorizes your application, the user is redirected to your redirect URL:

https://<your registered redirect URI>/?code=<authorization code>

The OAuth 2.0 authorization code is a randomly generated string. It is used in the next step, a request made to the token endpoint in exchange for an access token.

The response includes the state parameter, if it was in your request.

1. On your server, get an access token by making this request:

POST https://peerid.peerplays.download/api/v1/auth/exchange  
?code=<authorization code received in previous step>  
&client_id=<your client ID>  
&client_secret=<your client secret>

1. We respond with a json-encoded access token. The response looks like this:

{  
    "result": {  
        "expires": "<expiry date of the token>",  
        "app_id": <your client ID>,  
        "scope": <permissions granted by the user>,  
        "token": "<access token for the user>",  
        "refresh_token": "<refresh token for the user>"  
    },  
    "status": 200  
}

Store the access token and refresh token like passwords.

OAuth Resource Owner Password Credentials flow Follow the below steps to get the access token using the OAuth Resource Owner Password Credentials flow:

1. In your app, request for user's login credentials (i.e. username or email ID and mobile or password) and on your server, get an access token by making this request:

POST https://peerid.peerplays.download/api/v1/auth/token  
?login=<user's username or email ID>  
&password=<user's password>  
&mobile=<user's mobile number>  
&client_id=<your client ID>

Either password or mobile parameters has to be passed in this request. If both are passed, the PeerID server validates both of them along with the login.

1. We respond with a json-encoded access token. The response looks like this:

{  
    "result": {  
        "expires": "<expiry date of the token>",  
        "app_id": <your client ID>,  
        "scope": <permissions granted by the user>,  
        "token": "<access token for the user>",  
        "refresh_token": "<refresh token for the user>"  
    },  
    "status": 200  
}

Store the access token and refresh token like passwords.

4. Sending Access Tokens

Once you have the user’s access token, your app can perform the permitted operations on behalf of the user on the Peerplays blockchain using the /api/v1/app/operations API. You have to pass the access token for the user in the Authorization header for this API like:

curl -H "Authorization: Bearer <access token>" https://peerid.peerplays.download/api/v1/app/operations

The access token for one app cannot be used for another app.

5. Refreshing Access Tokens

New OAuth2 access tokens expire. Token-expiration periods vary in length, based on how and when the token was acquired. Tokens return an expires field indicating how long the token should last. However, you should build your applications in such a way that they are resilient to token authentication failures. In other words, an application capable of refreshing tokens should not need to know how long a token will live. Rather, it should be prepared to deal with the token becoming invalid at any time.

On seeing a 401 - Unauthorized error, an application should try to refresh the session if a refresh token is present. If the refresh fails, the application should re-prompt the end user with another authentication dialog via the standard OAuth 2.0 flow.

Generally, refresh tokens are used to extend the lifetime of a given authorization.

How to refresh a token:

To refresh a token, you need the refresh_token that you get in the response when you exchange your code for token and the client ID and client secret. The following API returns the new access token:

POST https://peerid.peerplays.download/api/v1/auth/refreshtoken  
?refresh_token=<refresh token for the user>  
&client_id=<your client ID>  
&client_secret=<your client secret>

The response will look like this:

{  
    "result": {  
        "expires": "<expiry date of the token>",  
        "app_id": <your client ID>,  
        "scope": <permissions granted by the user>,  
        "token": "<access token for the user>",  
        "refresh_token": "<refresh token for the user>"  
    },  
    "status": 200  
}

Once again, store the access token and refresh token like you would a password.

6. Glossary

OAuth (OAuth 2.0) - Open Authorization - An open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

CSRF Attacks - Cross-Site Request Forgery - A type of malicious exploit of a website where unauthorized commands are submitted from a user that the web application trusts.