SAML articles

Graphite metrics reporting in Connect2id server 3.8

Posted on 2016-01-13

Graphite Metrics

Graphite metrics reporting

The Connect2id server collects over 100 metrics on the usage of OpenID Connect single sign-on and the various OAuth grants. Admins are also provided with metrics to monitor the live performance of the server. Until now to get at that data you could either query the monitoring endpoint, or fetch it via a JMX dashboard.

The latest edition of the Connect2id server adds a third convenient option - streaming the metrics at an interval of your choice to a remote Graphite system. Graphite has become quite popular with admins and devops as of late, not least thanks to the powerful vis tool called Graphana.

To enable Graphite reporting edit the WEB-INF/ file. In addition to the server host / port where the metrics are to be streamed, you can also set a polling interval and multiple filters (with wild cards) to send only those metrics that are actually needed.

Check out its config manual for a detailed explanation of the parameters.

Example Graphite configuration:

monitor.graphite.enable = true =
monitor.graphite.port = 2003
monitor.graphite.reportInterval = 60
monitor.graphite.batchSize = 0
monitor.graphite.prefix = 31367e19-7a91-4bca-b457-9daca1f8ae3c.node1
monitor.graphite.ratesTimeUnit = SECONDS
monitor.graphite.durationsTimeUnit = MILLISECONDS
monitor.graphite.filter = *

Here is an example screenshot to show you what Graphite / Graphana are capable of. It does take some time to set them up, so you want to get started quickly take a look at Hosted Graphite, which is subscription based.

Client registration management

The Connect2id server provides a standard endpoint where OAuth clients are registered before they can request ID or access tokens from it.

You have various ways to manage client registrations:

  1. The manual way. Install a developer portal and manage registrations via it. The dev portal submits the approved client details to the registration endpoint, which is otherwise inaccessible to the outside world. This is the traditional approach for web apps, or apps that are confined within an enterprise.

  2. For mobile apps distributed via store. This method allows a mobile app client distributed via a store or similar channel to register itself dynamically with the Connect2id server. To manage this process the mobile apps can be provisioned with a software statement, a registration pass (a signed JWT) that also locks down specific registration parameters, such as the grant types and scope values that the client may register itself for.

  3. Pre-approved dynamic registration. The Connect2id server can also issue one-time tokens to register a client, which scope can be tailored to lock down registration to some permitted OAuth grants and other parameters.

  4. Some combination of 1, 2 and 3. Note that 2 and 3 overlap in many ways. They can also be automated services.

The latest release of the Connect2id server extends the special scopes for the initial registration tokens to allow scope values to be locked down.

This is best illustrated with an example:

Let’s say you want to issue an initial reg token to permit an OAuth client to make password grant requests for tokens with read and write scopes. In that case give the initial reg token the following scope values:


Don’t hesitate to contact Connect2id support if you think you need help with setting up an optimal and secure client registration for your system.

LDAP server response timeouts

Finally, two new configuration parameters were added to set an explicit timeout for LDAP responses from the directory backend:


To download a ZIP package of Connect2id server 3.8:

As WAR package only:


Please contact Connect2id support.

Connect2id Server 3.8 release notes


  • /WEB-INF/

    • Adds new op.reg.ldapServer.responseTimeout property to configure an explicit timeout (in milliseconds) for responses from the LDAP directory server where client registrations are persisted.
  • /WEB-INF/

    • Adds new authzStore.ldapServer.responseTimeout property to configure an explicit timeout (in milliseconds) for responses from the LDAP directory server where long-lived authorisations are persisted.
  • /WEB-INF/

    • Adds new monitor.graphite.* properties to enable and configure reporting Connect2id server metrics to a Graphite / Carbon server. Includes support for prefix / API key setting, time unit conversion and metric name filtering.
  • /WEB-INF/web.xml

    • The com.nimbusds.common.servlet.MonitorLauncher servlet context listener is invoked last to facilitate logging of all metrics names for reporting via Graphite.


  • /clients

    • Allows initial registration access tokens to specify the scope values that may be registered by the client. These are specified by giving the initial registration access token scope values of the form client-reg:scope:[scope-value] where [scope-value] denotes the permitted scope value that may be registered. For example, to allow a client to register for the openid and email scopes, create an initial registration token with the following scope: client-reg:scope:openid client-reg:scope:email.

Bug fixes

  • Ensures all paged LDAP searches that belong to a particular LDAP search request are performed on the same checked out LDAP connection (issues authz-store/109 and server/183).


  • Adds dependency to io.dropwizard.metrics:metrics-graphite:3.1.2

  • Upgrades to com.nimbusds:oauth2-authz-store:3.3

  • Upgrades to com.nimbusds:oidc-session-store:3.3

  • Upgrades to com.nimbusds:oauth2-oidc-sdk:5.1.1

  • Upgrades to com.nimbusds:common:1.98.1

  • Upgrades to com.thetransactioncompany:java-property-utils:1.10

Connect2id server 3.7 enables SAML 2.0 integration

Posted on 2015-12-28

Web API access token

SAML 2.0 integration

The latest release of the Connect2id server enables enterprises with applications utilising existing SAML IdP and SSO infrastructure to obtain OAuth access tokens for protected resources, typically web APIs.

How does this work?

  1. A user initiates login to an application;
  2. The application as a SAML 2.0 Service Provider (SP) redirects the user to the SAML 2.0 Identity Provider (IdP) and receives a SAML 2.0 assertion on success;
  3. If access to an OAuth 2.0 protected resource (e.g. web API) is required, the client exchanges the SAML 2.0 assertion for an access token at the token endpoint of the Connect2id server.

Use of SAML 2.0 assertions as OAuth grants is governed by RFC 7522. We ventured a step beyond the spec and added one potentially useful feature not present there — the ability to use the SAML assertion to request an OpenID identity token.

In case you need to meet complex requirements, the Connect2id server provides plenty of freedom and flexibility in defining how the SAML 2.0 assertions are to be converted to OAuth 2.0 access tokens:

  • Support for arbitrary credential sources and logic for validation of the SAML 2.0 assertions;
  • Logic to determine the scope of the issued OAuth tokens and its encoding, lifetime and other properties;
  • Mapping of client identifiers between the SAML IdP and the OAuth authorisation server.

Check out the SAML 2.0 assertion grant SPI docs for more information, or get in touch with our support team.

The Connect2id SDK for developing OAuth 2.0 and OpenID Connect apps was also upgraded and includes comprehensive support for handling SAML 2.0 assertions now.

Extended LDAP metrics

The monitoring API was extended to gather measurements and stats on the time it takes to complete LDAP requests to the directory backend:

  • LDAP get, search, modify and delete operations for the client registrations;
  • LDAP get, search, modify and delete operations for the long-lived authorisations.


To download a ZIP package of Connect2id server 3.7:

As WAR package only:


Please contact Connect2id support.

Connect2id Server 3.7 release notes


  • No changes


  • Discovery endpoint .well-known/openid-configuration:

    • Renames OpenID Provider metadata parameter for token introspection endpoint from "token_introspection_endpoint" to "introspection_endpoint" to match upcoming OAuth 2.0 specification (see draft-jones-oauth-discovery-00).

    • Renames OpenID Provider metadata parameter for token revocation endpoint from "token_revocation_endpoint" to "revocation_endpoint" to match upcoming OAuth 2.0 specification (see draft-jones-oauth-discovery-00).
  • Monitoring API monitor/v1/metrics:

    • Adds clientStore.ldapConnector.getTimer

    • Adds clientStore.ldapConnector.searchTimer

    • Adds clientStore.ldapConnector.addTimer

    • Adds clientStore.ldapConnector.modifyTimer

    • Adds clientStore.ldapConnector.deleteTimer

    • Adds authzStore.ldapConnector.getTimer

    • Adds authzStore.ldapConnector.searchTimer

    • Adds authzStore.ldapConnector.addTimer

    • Adds authzStore.ldapConnector.modifyTimer

    • Adds authzStore.ldapConnector.deleteTimer

Bug fixes

  • Ensures proper signature validation of self-issued OAuth 2.0 JWT bearer assertion grants (issue server/177).

  • Ensures proper shutdown of SPI implementations for handling OAuth 2.0 JWT bearer assertion grants issued by a third-party (issue server/178).

  • Logs asynchronous authorisation store LDAP results with codes 68 (entry already exists) and 32 (no such object) at info instead of error level.

  • Fixes AS00030 log message code (issue authz-store/107).


  • Upgrades to com.nimbusds:c2id-server-sdk:3.7.1

  • Upgrades to com.nimbusds:oauth2-authz-store:3.2

  • Upgrades to com.nimbusds:oidc-session-store:3.2.1

  • Upgrades to com.nimbusds:oauth2-oidc-sdk:5.1

  • Upgrades to com.nimbusds:nimbus-jose-jwt:4.11

  • Upgrades to com.unboundid:unboundid-ldapsdk:3.1.0

  • Upgrades to org.apache.commons:commons-collections4:4.1

  • Upgrades to org.apache.logging.log4j:log4j-web:2.5

  • Upgrades to org.apache.logging.log4j:log4j-slf4j-impl:2.5


  • Adds Java Service Provider Interface (SPI) for handling SAML 2.0 bearer assertion grants which are self-issued (created by the requesting client).

  • Adds Java Service Provider Interface (SPI) for handling SAML 2.0 bearer assertion grants which are issued by a third-party Security Token Service (STS).

The OAuth 2.0 / OpenID Connect toolkit for Java gets a makeover

Posted on 2015-12-16

OpenID Connect

Nothing stays the same at Connect2id, much less the core SDK for building OAuth 2.0 / OpenID Connect applications. Today it sees its 5th major release since 2012, when OpenID Connect was still an unknown and 2 years away from becoming a standard for SSO and authentication on the Internet.

Much of the technical debt from the early naive years of the SDK project is cleared away now. The good bits appreciated by developers are kept intact, or made even more awesome. Work on complementary specs in the identity space has not ceased, and this is reflected as support for the most recent OAuth RFC on token introspection or the authentication methods reference (still in progress). And yes, the bug cound in the tracker was driven all the way down to zero!

Highlights of the 5th release

  • A robust validator of ID tokens, be they signed, HMACed or encrypted. Issuer, audience and timestamp (with allowance for clock skew) checking is taken care of. The validating credentials are sourced according to their type, typically a local store for ID tokens HMACed with the client secret, or the provider’s JWK set endpoint (caching and RSA / EC key rotation supported out of the box).

  • New package for creating and consuming SAML 2.0 assertions, which can be used as a complementary grant in OAuth 2.0 to receive access and ID tokens (to be supported in this week’s release of the Connect2id server).

  • A revised package for dealing with JWT bearer assertions, which can also serve as an OAuth 2.0 grant or for assertion-based client authentication. Do take a look at JWT authentication, as it’s considerably safer than the commonly used HTTP basic auth. The client credential is not sent during authentcation, only an assertion (token) signed with it. This prevents accidental leakage of the client credential and other potential headaches.

  • New generic framework for verifying basic and JWT-based client authentication on the server side.

  • Adds classes for dealing with OAuth 2.0 token introspection (RFC 7662) requests and responses.

  • Adds OpenID Provider metadata support for custom (not registered) parameters, in case you need to handle such.

  • Did we mention — all reported bugs and issues have been fixed? :-)


Version 5.0 of the OAuth 2.0 / OpenID Connect SDK was pushed to Maven Central last night.

Here is its POM dependency:


How to convert SAML 2.0 assertions to OAuth 2.0 access tokens

Posted on 2014-05-15

Enterprises with existing SAML 2.0 based Single Sign-On (SSO) may sooner or later discover that they need to provide support for OAuth 2.0 in order to enable various mobile, consumer and social applications to grow their business.

Bridging the SAML and OAuth 2.0 frameworks is fortunately a well understood problem. The following stack of IETF specs provides a standard solution:

  • If you look at the core OAuth 2.0 spec (RFC 6749) and its token endpoint definition — this is basically an OAuth server endpoint which returns an access token in exchange for a "grant" — an open-ended concept of something deemed appropriate to grant the client app the issue of an access token. In the typical OAuth scenario this is an authorisation code signifying that the user has been previously authenticated and given their consent. But the grant could also be something else.

  • There is a further IETF spec called draft-ietf-oauth-assertions-16 that builds on the core RFC 6749 standard which says that the grant can also be an assertion (a signed proof of something) and defines the necessary token request parameters for that.

  • Finally, there is draft-ietf-oauth-saml2-bearer-20, which specifies how this assertion can be a SAML 2.0 Bearer Assertion.

Support of this mechanism for converting SAML 2.0 assertions to OAuth 2.0 access is planned for a next release of the Connect2id server. Until then the existing universal endpoint for direct authorisation (meant for integrating external logins, e.g. Facebook or Google) can be utilised to achieve the same effect.

To ensure removal of users in the SAML provider is properly reflected by the OAuth 2.0 authorisation systems there are two approaches, which can be effectively combined:

  • Make the OAuth 2.0 access tokens short lived. This will force the client to repeat the authorisation process when the token expires, and if the user no longer exists authentication will fail and no grant (SAML assertion) will be issued.
  • Provide an API for revoking issued OAuth 2.0 access tokens, see RFC 7009 for details.