Login Tokens
From Social ID Developers
(Difference between revisions)
Renato.neves (Talk | contribs) |
(→connection_id) |
||
| (43 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | == Tokens == | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | = | + | === login_token === |
| − | + | It is the token generated each time a visitor performs a login. | |
| − | + | The token is returned on the [[socialid.events.onLoginSuccess]] event or sent as a parameter to the callback url configured on the Login application. | |
| − | + | Characteristics: | |
| + | * Created: every time the user logs in. | ||
| + | * Validity: expires in 1 hour. | ||
| − | + | APIs: | |
| − | * | + | * It is used to authenticate the [[GET login/info]] API call. |
| − | * | + | |
| + | === connection_id === | ||
| + | |||
| + | It is an identifier generated for each visitors' active connection. It represents the Login session for the current visitor. | ||
| + | |||
| + | The Social Login widgets automatically identifies users logged in, given the connection_id saved on a cookie on the visitor's browser. | ||
| + | |||
| + | <!-- See [[Single Sign On User Guide|Single Sign On]] for more information on how to implement Single Sing On using the connection_id. --> | ||
| + | |||
| + | Characteristics: | ||
| + | * Created: every time the user logs in or using an API call. | ||
| + | * Validity: expires according to "Session Lifetime" configuration defined in the Login application. | ||
APIs: | APIs: | ||
| − | * | + | * In order to generate a new connection_id given a user id, use the [[POST login/apps/:app_id/sign_ins]] REST API. |
| + | * In order to log in a user on a Login session given a connection_id, use the [[socialid.login.loginConnection]] Javascript API. | ||
| + | * In order to log off a user from a Login session, use the [[socialid.login.logout]] Javascript API or the [[DELETE login/connections/:id]] REST API. | ||
| + | * In order to check for a current connection_id, use the [[socialid.login.getConnectionStatus]] Javascript API. | ||
| + | * In order to validate a connection_id and retrieve the user profile associated with it, use the [[GET login/connections/:id]] REST API. | ||
| − | == | + | === user_token === |
| − | + | It is a token used in a few JavaScript APIs to identify the user in a secure way. | |
| − | + | Characteristics: | |
| + | * Created: when the user is created. | ||
| + | * Updated: every time the user logs in or via API. | ||
| + | * Validity: never expires. | ||
| − | + | APIs: | |
| − | * | + | * The [[PUT login/users/:user_id/token]] API updates a user's token. |
| − | * | + | * Given a user_token, it is possible to log in a user on a Login session (generating a new connection_id) using the [[socialid.login.loginUserToken]] JavaScript API. |
| + | |||
| + | === access_token === | ||
| + | |||
| + | It is a token provided by OAuth2 APIs through the [[OAuth_APIs#Token_Endpoint|token endpoint]]. This token is used to access OAuth2 resources. | ||
| + | |||
| + | Characteristics: | ||
| + | * Created: every time the user logs in using OAuth2 APIs. | ||
| + | * Validity: expires according to "OAuth Access Token Expiration" configuration defined in the Login application. | ||
APIs: | APIs: | ||
| − | * | + | * [[OAuth_APIs#Token_Endpoint|Token endpoints]] generate access tokens. |
| − | + | ||
| − | + | ||
| − | == | + | === refresh_token === |
| − | + | It is a token provided by OAuth2 APIs through the [[OAuth_APIs#Token_Endpoint|token endpoint]]. This token is used to retrieve a new access token after expiration. | |
| − | + | Characteristics: | |
| − | * | + | * Created: every time an access token is generated. |
| − | * | + | * Validity: expires according to "OAuth Refresh Token Expiration" configuration defined in the Login application. Also, it's revoked after used. |
APIs: | APIs: | ||
| − | * | + | * [[OAuth_APIs#Token_Endpoint|Token endpoints]] generate access tokens and their associated refresh tokens. |
| − | * | + | * [[POST_/oauth/token_refresh_token]] refreshes an access token, generating a new one given a refresh token. |
| + | |||
| + | === id_token === | ||
| + | |||
| + | It's a JWT token provided by OAuth2 APIs used in combination with OpenID Connect (OIDC) Protocol. | ||
| + | |||
| + | Characteristics: | ||
| + | * Created: every time an access token for OIDC is generated using the response_type id_token in the Authorization request. | ||
| + | * Validity: expires according to "JWT Expiration" configuration defined in the Login application. | ||
| + | |||
| + | == Security == | ||
| + | |||
| + | The REST APIs use the HTTP Basic protocol for authentication. See the [[Authentication]] documentation. | ||
| + | |||
| + | The JavaScript APIs use the session of the user currently logged in, or identifiers like connection_id and user_token as authentication parameters. | ||
| + | |||
| + | JavaScript APIs requires a bigger effort to ensure security because they are used on the visitor's browser (i.e. it is not possible to guarantee JavaScript code validity) and in unpredictable conditions (i.e. in public, non-encrypted Wi-Fi networks). As with any browser session, JavaScript APIs may be subject to [http://en.wikipedia.org/wiki/Session_hijacking Session Hijacking] or [http://en.wikipedia.org/wiki/Man-in-the-middle_attack Man-in-the-middle], among others. | ||
| + | |||
| + | To minimize security risks, we show below a list of good practices. Developers using our APIs need to be aware that the indiscriminate use of connection_id and user_token identifiers may increase those risks. | ||
| + | |||
| + | === Good Practices === | ||
| + | |||
| + | * Log the user off from Login session every time he/she logs off your application. Use the [[socialid.login.logout]] JavaScript API or the [[DELETE login/connections/:id]] REST API. | ||
| + | |||
| + | * Update the user_token periodically using the [[PUT login/users/:user_id/token]] REST API. Since the user_token doesn't expire and may be used on critical JavaScript APIs (e.g. to log in or move users), it is advisable to update this token periodically to avoid [http://en.wikipedia.org/wiki/Session_hijacking Session Hijacking]. | ||
| + | |||
| + | * Use secure connections ([http://en.wikipedia.org/wiki/Https HTTPS]) on your website to avoid tokens to be intercepted by attackers on unprotected networks. See [http://en.wikipedia.org/wiki/Man-in-the-middle_attack Man-in-the-middle attack]. | ||
| + | |||
| + | * Avoid storing any tokens in cookies. If you must, use the "[http://en.wikipedia.org/wiki/HTTP_cookie#Secure_and_HttpOnly secure]" attribute on the cookie. | ||
| + | |||
| + | * Use [[RESTful APIs]] only on backend, never via JavaScript (frontend). The API ID and Secret that are used as [[Authentication]] must not be exposed on a users's browser. | ||
| + | |||
| + | * Use extra authentication (e.g. login/password authentication) in critical operations of your website (financial operations, credit card data management, etc). | ||
Latest revision as of 22:05, 17 February 2022
Contents |
Tokens
login_token
It is the token generated each time a visitor performs a login.
The token is returned on the socialid.events.onLoginSuccess event or sent as a parameter to the callback url configured on the Login application.
Characteristics:
- Created: every time the user logs in.
- Validity: expires in 1 hour.
APIs:
- It is used to authenticate the GET login/info API call.
connection_id
It is an identifier generated for each visitors' active connection. It represents the Login session for the current visitor.
The Social Login widgets automatically identifies users logged in, given the connection_id saved on a cookie on the visitor's browser.
Characteristics:
- Created: every time the user logs in or using an API call.
- Validity: expires according to "Session Lifetime" configuration defined in the Login application.
APIs:
- In order to generate a new connection_id given a user id, use the POST login/apps/:app_id/sign_ins REST API.
- In order to log in a user on a Login session given a connection_id, use the socialid.login.loginConnection Javascript API.
- In order to log off a user from a Login session, use the socialid.login.logout Javascript API or the DELETE login/connections/:id REST API.
- In order to check for a current connection_id, use the socialid.login.getConnectionStatus Javascript API.
- In order to validate a connection_id and retrieve the user profile associated with it, use the GET login/connections/:id REST API.
user_token
It is a token used in a few JavaScript APIs to identify the user in a secure way.
Characteristics:
- Created: when the user is created.
- Updated: every time the user logs in or via API.
- Validity: never expires.
APIs:
- The PUT login/users/:user_id/token API updates a user's token.
- Given a user_token, it is possible to log in a user on a Login session (generating a new connection_id) using the socialid.login.loginUserToken JavaScript API.
access_token
It is a token provided by OAuth2 APIs through the token endpoint. This token is used to access OAuth2 resources.
Characteristics:
- Created: every time the user logs in using OAuth2 APIs.
- Validity: expires according to "OAuth Access Token Expiration" configuration defined in the Login application.
APIs:
- Token endpoints generate access tokens.
refresh_token
It is a token provided by OAuth2 APIs through the token endpoint. This token is used to retrieve a new access token after expiration.
Characteristics:
- Created: every time an access token is generated.
- Validity: expires according to "OAuth Refresh Token Expiration" configuration defined in the Login application. Also, it's revoked after used.
APIs:
- Token endpoints generate access tokens and their associated refresh tokens.
- POST_/oauth/token_refresh_token refreshes an access token, generating a new one given a refresh token.
id_token
It's a JWT token provided by OAuth2 APIs used in combination with OpenID Connect (OIDC) Protocol.
Characteristics:
- Created: every time an access token for OIDC is generated using the response_type id_token in the Authorization request.
- Validity: expires according to "JWT Expiration" configuration defined in the Login application.
Security
The REST APIs use the HTTP Basic protocol for authentication. See the Authentication documentation.
The JavaScript APIs use the session of the user currently logged in, or identifiers like connection_id and user_token as authentication parameters.
JavaScript APIs requires a bigger effort to ensure security because they are used on the visitor's browser (i.e. it is not possible to guarantee JavaScript code validity) and in unpredictable conditions (i.e. in public, non-encrypted Wi-Fi networks). As with any browser session, JavaScript APIs may be subject to Session Hijacking or Man-in-the-middle, among others.
To minimize security risks, we show below a list of good practices. Developers using our APIs need to be aware that the indiscriminate use of connection_id and user_token identifiers may increase those risks.
Good Practices
- Log the user off from Login session every time he/she logs off your application. Use the socialid.login.logout JavaScript API or the DELETE login/connections/:id REST API.
- Update the user_token periodically using the PUT login/users/:user_id/token REST API. Since the user_token doesn't expire and may be used on critical JavaScript APIs (e.g. to log in or move users), it is advisable to update this token periodically to avoid Session Hijacking.
- Use secure connections (HTTPS) on your website to avoid tokens to be intercepted by attackers on unprotected networks. See Man-in-the-middle attack.
- Avoid storing any tokens in cookies. If you must, use the "secure" attribute on the cookie.
- Use RESTful APIs only on backend, never via JavaScript (frontend). The API ID and Secret that are used as Authentication must not be exposed on a users's browser.
- Use extra authentication (e.g. login/password authentication) in critical operations of your website (financial operations, credit card data management, etc).
