How to enable and manage native SSO

This guide explains how to configure a Connect2id server so that groups of native mobile and desktop apps can use the OpenID Connect extension for native SSO. It also describes the registration of native clients and the management of native client group (NCG) sessions.

Configuration

Enable native client group SSO in the Connect2id server.
```
op.sso.nativeClientGroup.enable=true
```
This capability will be advertised in the OpenID provider metadata via the native_sso_supported parameter.

Choose suitable time settings for the native client group sessions, or leave the
defaults.

Example session time settings (all values in minutes):

# Limit the lifetime of sessions to 90 days
op.sso.nativeClientGroup.sessionMaxLifetime=129600
# Don't ask users to periodically re-authenticate 
op.sso.nativeClientGroup.sessionAuthLifetime=0
# End sessions after 10 days of inactivity (no token requests)
op.sso.nativeClientGroup.sessionMaxIdleTime=14400

Enable the default handler for back-channel SSO authorisations.
```
op.deviceSSOHandler.enable=true
```
The default handler supports a number of optional settings, such as scope values that require the user to re-authenticate and / or provide explicit consent at the authorisation endpoint.
```
op.deviceSSOHandler.enable=true
op.deviceSSOHandler.scopeRequiringInteraction=email profile
```

Native app registration

A mobile or desktop app is eligible to use native SSO when it is registered with a scope metadata parameter that includes both openid and device_sso.

Example client registration request for a public client that is part of a native client group:

POST /clients HTTP/1.1
Host: demo.c2id.com
Content-Type: application/json

{
  "application_type"           : "native",
  "redirect_uris"              : [ "https://app.example.com/cb" ],
  "token_endpoint_auth_method" : "none",
  "code_challenge_method"      : "S256",
  "scope"                      : "openid device_sso email profile"
}

To register the client for DPoP-bound tokens and device_secrets, use the dpop_bound_access_tokens parameter. Enabling this requires the client to include a DPoP proof header in all token requests. When DPoP is required for a group of native clients, the DPoP key must be shared by all clients in the group, and its lifecycle must be managed accordingly.

POST /clients HTTP/1.1
Host: demo.c2id.com
Content-Type: application/json

{
  "application_type"           : "native",
  "redirect_uris"              : [ "https://app.example.com/cb" ],
  "token_endpoint_auth_method" : "none",
  "code_challenge_method"      : "S256",
  "dpop_bound_access_tokens"   : true,
  "scope"                      : "openid device_sso email profile",
}

See the client registration guide for additional tips on registering native apps as public OAuth 2.0 clients.

Managing the native client group sessions

Active sessions for a user can be obtained through the Connect2id server’s session store API. The sessions that are for native client groups have a ctx field set to NCG.

Example request to list the native client group sessions for a user alice:

GET /session-store/rest/v2/sessions?subject=alice&ctx=NCG HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

To end a session, use the DELETE method.

Example request to delete a session by its identifier:

DELETE /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw