Introduction: About SSO
Single Sign-On (SSO) allows users to log in once and gain access to multiple applications without needing to re-authenticate for each one. It improves user experience by centralizing authentication. It can also enhance security since it reduces the number of passwords the user must know.
Single Sign-off allows signing off from all applications at once.
AllegroGraph implements SSO using OpenID Connect (OIDC), which is a modern authentication protocol built on top of OAuth 2.0. OIDC adds a layer of identity management, allowing applications to authenticate users based on the identity information provided by an external authorization server.
The Connection between SSO and OIDC
OIDC as an SSO Protocol: OIDC is often used to implement SSO because it provides a standardized way for users to authenticate and authorize access to multiple applications. OIDC allows applications (called Relying Parties) to trust an external Identity Provider (IdP) for authentication.
How It Works in Practice with AllegroGraph
In order to enable log in with an SSO server, the AllegroGraph configuration file must contain an OAuth directive. See Top-level directives for external authentication) in the Server Configuration and Control document.
Logging out is supported by the front-channel-logout and back-channel-logout, which should be specified as shown (though yes is the default value for both). See the descriptions of thos arguments following the link just above.
The directive specification looks like this (the client values shown are invalid though in the correct form: you must supply values from your own OAuth server):
OAuth server="http://auth.example.com:4444", \
authorize-endpoint="/oauth2/auth", \
token-endpoint="/oauth2/token", \
jwks-uri="http://auth.example.com:4444/.well-known/keys.json", \
jws-algorithms="RS256, RS512", \
client-id="cc8b0524-ad95-47e8-977d-f3a70e5279a1", \
client-secret="J-k64I.gIC9xD9OM7d9bczKDJ5", \
scope="openid", \
username-claim="sub", \
username-regexp="^(.*)@.*", \
username-substitution="\\1", \
pkce=yes, \
front-channel-logout=yes, \
back-channel-logout=yes
If that directive is present in the agraph.cfg file, then when the user desires to log into AllegroGraph using WebView, the log in dialog displayed will look like:
Note the button SIGN IN WITH SSO near the bottom. (That button will not appear in the dialog unless there is a valid OAuth entry in agraph.cfg.)
Here AllegroGraph is the relying party and the identity provider is specified by the server entry.
When registering AllegroGraph as a client application, the following AllegroGraph HTTP endpoints may be important:
GET /oauth/login
GET, POST /oauth/logout The first one is the main redirect URI: authorization service should redirect to this URI after the user approved access. Normally one does not need to worry about this, since application callback URI is sent to the authorization service as part of the initial redirect to it during SSO login, but some authorization services require allowed application redirect URIs to be specified beforehand.
The second one is an endpoint for OpenID Connect Front-Channel Logout (GET) and OpenID Connect Back-Channel Logout (POST). This is usually required during client registration in order to enable OIDC Single Logout.
We do not provide details of OAuth behavior in this AllegroGraph documentation beyond noting that the user authentification can last beyond the SSO user logout from AllegroGraph (this of course does depend on your OAuth setup). So if the user USER1 logs into AllegroGraph using SSO and then logs out, but the authorization service stored their decisions (usually a Remember my decision checkbox or something similar), and another user logs in (not using SSO) and subsequently logs out so the login dialog is visible, clicking Sign in with SSO will (again, depending on the OAuth setup) log USER1 in again. That is likely expected and desired behavior but may be a surprise to some.
Usernames and permissions must be specified within AllegroGraph
A user who logs in via OAuth SSO must have a username defined within AllegroGraph. No password need be specified, as shown here where selecting External authentication in the WebView new user field grays out the password fields:
Also additional user permissions and Catalog/Repository access must be specified within AllegroGraph as described in the Managing Users document. (The illustration is from WebView but agtool can also be used, of course.)
SSO users and other AllegroGraph tools such as agtool
OpenID Connect ID tokens can be used directly to authenticate calls to AllegroGraph HTTP API endpoints. Tokens are obtained from the user's system administrator in some fashion. There is no way to obtain a token from within AllegroGraph. In what follows, we assume the user has obtained the necessary token.
In order to use an ID token for API call authentication, it must be sent in an Bearer HTTP authorization header
Authorization: Bearer <id-token> but for compatibility purposes (especially for agtool, as explained below) ID tokens can also be used in place of passwords in Basic HTTP authorization:
Authorization: Basic base64(<username>:<id-token>) Note that with Bearer authorization scheme, username is not needed as it is embedded in the ID token itself, but Basic authorization requires username to be specified. The username must match the one that is going to be inferred from the ID token based on OAuth configuration options.
agtool is a command line interface to AllegroGraph. It often takes as an argument a server spec or a repo spec. These specifications are documented in the Repository Specification document. The simple general form of a specification typically looks like
user:password@host:port[s]
user:password@host:port[s]/[catalog:]repo Now an SSO user will not usually have an AllegroGraph password, so an OIDC ID token can be used instead of a password, and will be sent to the AllegroGraph server in the Basic HTTP authorization header
sso-user:id-token@host:port
sso-user:id-token@host:port/[catalog:]repo ID tokens are base64url-encoded, so it is always syntactically safe to use them in AllegroGraph server and repo specifications.