GUACAMOLE-519: Implement Single Logout on OpenID Extension

[bayars]

Related Issues:

• GUACAMOLE-519: Implement Single Logout on OpenID Extension
• GUACAMOLE-758: OpenID Guacamole Logout

General SSO Design

When registering Guacamole with your OpenID Connect provider, you will typically need to provide:

1. Redirect URI / Callback URL: The full URL to your Guacamole installation (e.g., https://guacamole.example.com/guacamole/)
2. Post-Logout Redirect URI: The URL to redirect to after logout (typically the same as the redirect URI)
3. Client Type: Public client (Guacamole uses the implicit flow)
4. Allowed Scopes: openid, email, profile, and optionally groups

Single Logout Behavior

When openid-logout-endpoint is configured:

1. User clicks logout in Guacamole
2. Guacamole session is terminated
3. User is redirected to the identity provider's logout endpoint
4. Identity provider terminates the SSO session
5. User is redirected back to openid-post-logout-redirect-uri (or openid-redirect-uri if not specified)

The logout request includes:

• post_logout_redirect_uri: Where to redirect after logout
• id_token_hint: The user's ID token (if available), or
• client_id: The Guacamole client ID (if ID token is not available)

Example Configurations:

I have tested with the Keycloak only. I am not sure for others, but others have similar integrations/variables.

Keycloak Configuration

# Keycloak OpenID Connect settings                                                                                                                                                                                                                           
openid-authorization-endpoint: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/auth                                                                                                                                                      
openid-jwks-endpoint: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs                                                                                                                                                              
openid-issuer: https://keycloak.example.com/realms/myrealm                                                                                                                                                                                                   
openid-client-id: guacamole                                                                                                                                                                                                                                  
openid-redirect-uri: https://guacamole.example.com/guacamole/                                                                                                                                                                                                

# Optional: Use preferred_username instead of email                                                                                                                                                                                                          
openid-username-claim-type: preferred_username                                                                                                                                                                                                               

# Optional: Enable Single Logout                                                                                                                                                                                                                             
openid-logout-endpoint: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/logout                                                                                                                                                           
openid-post-logout-redirect-uri: https://guacamole.example.com/guacamole/                                                                                                                                                                                    

Okta Configuration

# Okta OpenID Connect settings                                                                                                                                                                                                                               
openid-authorization-endpoint: https://your-domain.okta.com/oauth2/default/v1/authorize                                                                                                                                                                      
openid-jwks-endpoint: https://your-domain.okta.com/oauth2/default/v1/keys                                                                                                                                                                                    
openid-issuer: https://your-domain.okta.com/oauth2/default                                                                                                                                                                                                   
openid-client-id: your-client-id                                                                                                                                                                                                                             
openid-redirect-uri: https://guacamole.example.com/guacamole/                                                                                                                                                                                                

# Optional: Enable Single Logout                                                                                                                                                                                                                             
openid-logout-endpoint: https://your-domain.okta.com/oauth2/default/v1/logout                                                                                                                                                                                

Azure AD Configuration

# Azure AD OpenID Connect settings                                                                                                                                                                                                                           
openid-authorization-endpoint: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize                                                                                                                                                           
openid-jwks-endpoint: https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys                                                                                                                                                                      
openid-issuer: https://login.microsoftonline.com/{tenant-id}/v2.0                                                                                                                                                                                            
openid-client-id: your-application-client-id                                                                                                                                                                                                                 
openid-redirect-uri: https://guacamole.example.com/guacamole/                                                                                                                                                                                                

# Azure AD uses 'preferred_username' claim                                                                                                                                                                                                                   
openid-username-claim-type: preferred_username                                                                                                                                                                                                               

# Optional: Request groups in token                                                                                                                                                                                                                          
openid-scope: openid email profile groups                                                                                                                                                                                                                    

# Optional: Enable Single Logout                                                                                                                                                                                                                             
openid-logout-endpoint: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/logout                                                                                                                                                                     

Google Configuration

# Google OpenID Connect settings
openid-authorization-endpoint: https://accounts.google.com/o/oauth2/v2/auth
openid-jwks-endpoint: https://www.googleapis.com/oauth2/v3/certs
openid-issuer: https://accounts.google.com
openid-client-id: your-client-id.apps.googleusercontent.com
openid-redirect-uri: https://guacamole.example.com/guacamole/

Auth0 Configuration

# Auth0 OpenID Connect settings
openid-authorization-endpoint: https://your-domain.auth0.com/authorize
openid-jwks-endpoint: https://your-domain.auth0.com/.well-known/jwks.json
openid-issuer: https://your-domain.auth0.com/
openid-client-id: your-client-id
openid-redirect-uri: https://guacamole.example.com/guacamole/

# Optional: Enable Single Logout
openid-logout-endpoint: https://your-domain.auth0.com/v2/logout 

[necouchman]

@bayars

• Your commit messages all need to container the GUACAMOLE-519: prefix.
• The pull request needs to be properly titled with a : between the Jira issue and the rest of the message.

[bayars]

@necouchman done. Please recheck again

[necouchman]

@bayars Looks good to me. The documentation you provided in the pull request is quite good, we'll want to make sure that gets added to the appropriate section of apache/guacamole-manual.

[necouchman]

Thanks @bayars! If you could update the manual, as well (apache/guacamole-manual repo), and open a PR for that, that would be great!

[bayars]

Thanks @bayars! If you could update the manual, as well (apache/guacamole-manual repo), and open a PR for that, that would be great!

Thank you, I will create a separate Mr on this weekend.