Endpoints
The PERCEIVE Portal implements OAuth 2.0 for secure authentication and authorization, adhering closely to the protocol defined in RFC 6749. This document outlines the three main OAuth 2.0 endpoints used within the PERCEIVE Portal: the Authorization Endpoint, the Token Endpoint, and a custom Logout Endpoint. Each endpoint plays a crucial role in the OAuth 2.0 flow, ensuring secure and efficient user authentication and authorization.
Authorization Endpoint:
The Authorization Endpoint is the starting point for the OAuth 2.0 Authorization Code flow. It is responsible for authenticating the resource owner (user) and obtaining their authorization to grant an access token to the client.
Endpoint URL:
/connect/authorize(GET and POST)RFC Reference:
General: Section 3.1 of RFC 6749
Authorization Request: Section 4.1.1 of RFC 6749
Parameters
- client_id
REQUIRED. The client identifier which can be found in Clients and scopes.
- code_challenge
REQUIRED. The PKCE Code for Proof Key for Code Exchange.
- code_challenge_method
REQUIRED. Value must be set to the challenge method used such as
S256.- redirect_uri
OPTIONAL. After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent back to the client.
- response_type
REQUIRED. Value MUST be set to "code".
- scope
OPTIONAL. The scope of permissions the client requests. The allowed scopes can be found in Clients and scopes.
- state
RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery as described in Section 10.12 of RFC6749
Token Endpoint:
The Token Endpoint exchanges an authorization code for an access token and, in some flows, a refresh token. This endpoint is used both for the initial token request following the Authorization Code flow and for subsequent access token refresh requests.
Endpoint URL:
/connect/token(POST)RFC Reference:
General: Section 3.2 of RFC 6749
Access Token Request: Section 4.1.3 of RFC 6749
Refreshing an Access Token: Section 6 of RFC 6749
Clients make a POST request to this endpoint with the authorization code (or a refresh token) to obtain an access token. The request must include parameters such as grant_type, code, redirect_uri, client_id, and code_verifier for PKCE.
Parameters
- client_id
REQUIRED. The client identifier which can be found in Clients and scopes.
- code
REQUIRED. The authorization code received from the authorization server.
- code_verifier
REQUIRED. The original code verifier used to generate the challenge
- redirect_uri
REQUIRED. If the "redirect_uri" parameter was included in the authorization request, and their values MUST be identical.
- response_type
REQUIRED. Value MUST be set to "authorization_code" OR "refresh_token" depended on the token you want to request.
Logout Endpoint:
The Logout Endpoint is a custom addition to the standard OAuth 2.0 protocol, designed to facilitate secure logout functionality. Calling this endpoint will remove all session cookies, effectively logging out the user from the application.
Endpoint URL:
/connect/logout(POST)
This endpoint should be called when a user chooses to log out of the application. It ensures that the user's session is completely terminated, enhancing security by preventing unauthorized access to previously authenticated sessions.