CitizenOne Integration

Interested in learning more about integrating with CitizenOne?

View the information below or contact us to request additional CitizenOne documentation.

API Information

Visit for more information or contact us with direct questions.


Vivvo follows SAML2 protocol standards in our IDP service.  This service allows relying parties to register their client metadata with CitizenOne requesting what features of the protocol they wish to use. 

The CitizenOne SAML service offers a dynamic endpoint so that the latest metadata can be polled.  We recommend that the relying parties use this service so they always have the most updated information.

For more information on this specification please see (


Vivvo follows Oauth2 core standards, and allows for front and back channel flows. We issue access tokens and refresh tokens following the OIDC specification for open interoperability with relying parties.

For more information on this specification please see (


Vivvo uses JWT tokens to represent the authenticated user.  When a cookie is set using the ClientSSO token the cookies follows this standard. 

For more information on this specification please see (

Single Logout

Session Persistence and logout considerations

Please use these only as examples in planning your enterprise policy.

When implementing single log out there are three layers to consider:

1. Application Session Layer

This layer is the space inside your application that tracks that the authenticated context. When handing off a globally authenticated user to your applications, your application normally creates a cookie that stores the global authentication token in the users’ cookie space, and this is used as evidence that the user has been authorized.

The life cycle of this cookie is handled by the application and not the IDP provider. If the IDP shared access to the same cookie space (same fully qualified domain name) then the IDP can remove the cookie, but it is still the responsibility of the application to check regularly that this cookie still persists.

Application session timer

Vivvo recommends that you create a session max idle time for the application that matches the privacy tolerance for that application. For example:

For applications that:

  1. Expose potentially sensitive data session idle time: 10 minutes
  2. Expose basic information about the individual session idle time: 60 minutes
  3. Expose no personally identifiable information session idle time: 8 hours.

2. Identity Session Layer

CitizenOne creates a session for the user that is registered locally for the authenticated user. This session can be refreshed by any service provider to extend the session timeout by sending a POST request to the CitizenOne rest endpoint at (https://{baseUrl}/sp/api/v1/authenticate?type=token) with the request body:


   “token”: “{{authToken}}”,

   “refresh”: “true”


This session is referenced where there is a login request from a provider or relying party asking for an authenticated user request. If the user has an active session in this layer a response is generated to the party, if there is not session the user is sent to the login module.

3. CitizenOne Session Layer

This session allows the user to use the CitizenOne application in an authenticated state, just like in the application session space. This layer is reliant on the presence of the cookie that has been created from the IDP session response.

Note to the IDP owner: The IDP can authenticate a user for an application, but it is ultimately the responsibility of the application provider to align the session life cycle with the IDP session policy. 

Note to the application Owner: If you are using the SAML authentication you will need to have a relying party endpoint that can accept a logout request, remove your application sessions and then issue a SAML success response back to the IDP.

More information on the schema and flows can be found at (

CitizenOne Logout Strategy for JWT

JWT offers the lowest amount of complexity for single sign-out. This requires however all included applications to belong to the same base domain (e.g. The session cookie is created in this space for all applications after authentications. This session is shared and managed by all applications in the domain. The security implications of this are as follows:

  1. Any application can read this cookie regardless of the state of consent.
  2. Any application can delete this cookie and log out of all applications.

Creating a cookie at this level is necessary however to display attributes in the profile section of the global header. One could argue though, that all applications in the namespace are trusted authorized applications that would not abuse this space.

Any application in the client site domain can terminate all applications. The flow from the SAML single sign-out will log out all JWT dependent applications including the CitizenOne service dashboard and business connect web applications.

CitizenOne Logout Strategy for Oauth2.0

OAuth is an open-standard authorization protocol that describes how unrelated servers and services can safely allow authenticated access to their assets without actually sharing the initial, related, single logon credential. In authentication parlance, this is known as secure, third-party, user-agent, delegated authorization.

CitizenOne implements Oauth2 core functionality.  Dynamic features are on our roadmap for self-registration.  There is a draft specification for OIDC single logout (more information can be found at:  Vivvo follows draft specifications, but the implementation does not reach our roadmap until they are past the draft state and are officially approved.  If our clients require a pre-release implementation of this specification, we can add it and evolve it as the specification matures.