Authentication
GGCE uses OpenID Connect (OIDC), a simple identity layer on top of the OAuth 2.0 protocol to authenticate users and systems.
You can authenticate as a user or as a service to obtain the access token to interact with the API. A valid access token does not immediately grant you permission to all endpoints. There are security checks in place.
Tokens are in JWT format and you can check the contents of any JWT token with https://jwt.io
OAuth clients
There is a big difference between the user of your application and the application itself. When a user (usually a person) interacts with your application (a service) then all actions in GGCE will be executed on behalf of the user. The application itself can also execute actions in GGCE as a service.
For example, an application that reads data from GGCE and checks for spelling errors will authenticate with GGCE as a service. If a person then logs into this application to fix the spelling errors, they authenticate as a user.
In both cases, the application is registered as an OAuth client in GGCE, and will have its own client_id and possibly a client_secret.
Registering a new client
See Admin > OAuth clients in GGCE Web interface.
OIDC endpoints
A number of endpoints are involved in OIDC authentication and they are listed at /.well-known/openid-configuration path, for example https://demo.ggceapi.genesys-pgr.org/.well-known/openid-configuration. Most OIDC libraries will automatically access this URL and use it for auto-configuration.
Authenticating as a service
This is called client authentication and it is possible to obtain tokens with a simple call to /oauth2/authenticate endpoint.
The best approach is to add an existing OIDC library to your application and let it handle the authentication flow, providing your application only with the final access and, optionally, refresh tokens.
Authenticating a user
Authenticating a user is a much more engaged process. OIDC requires that the username and password are not provided to the service (i.e. using a login form), and must only be provided to the authentication server. This also means that out-of-band authentcation (OOB) is no longer possible.
The best approach is to use an existing OIDC library and let it handle the user authentication flow, providing your application only with the final access and, optionally, refresh tokens.
Example with Postman
TBD.