Security Providers

Implemented Security Providers

Helidon provides the following security providers for endpoint protection:

Provider	Type	Outbound supported	Description
OIDC Provider	Authentication	✅	Open ID Connect supporting JWT, Scopes, Groups and OIDC code flow
HTTP Basic Authentication	Authentication	✅	HTTP Basic Authentication support
HTTP Digest Authentication	Authentication	🚫	HTTP Digest Authentication support
Header Assertion	Authentication	✅	Asserting a user based on a header value
HTTP Signatures	Authentication	✅	Protecting service to service communication through signatures
IDCS Roles	Role Mapping	🚫	Retrieves roles from IDCS provider for authenticated user
ABAC Authorization	Authorization	🚫	Attribute based access control authorization policies

The following providers are no longer evolved:

Provider	Type	Outbound supported	Description
Google Login	Authentication	✅	Authenticates a token from request against Google servers
JWT Provider	Authentication	✅	JWT tokens passed from frontend

Note: If the example code uses clear-text passwords in configuration, ensure that you add the following to the code snippet:

security:
  config.require-encryption: false

Copied

If set to true, an exception is thrown. However, in a production environment, you would set this value to true so that any attempt to pass a clear-text password throws an exception.

OIDC Provider

Open ID Connect security provider.

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.microprofile</groupId>
    <artifactId>helidon-microprofile-oidc</artifactId>
</dependency>

Copied

Open ID Connect security provider

Type: io.helidon.security.providers.oidc.OidcProvider

Config key

oidc

Copied

This type provides the following service implementations:

io.helidon.security.spi.AuthenticationProvider
io.helidon.security.spi.SecurityProvider

Configuration options

Optional configuration options

key	type	default value	description
`audience`	string		Audience of issued tokens.
`authorization-endpoint-uri`	URI		URI of an authorization endpoint used to redirect users to for logging-in. If not defined, it is obtained from #oidcMetadata(Resource), if that is not defined an attempt is made to use #identityUri(URI)/oauth2/v1/authorize.
`base-scopes`	string	`openid`	Configure base scopes. By default this is `DEFAULT_BASE_SCOPES`. If scope has a qualifier, it must be used here.
`client-id`	string		Client ID as generated by OIDC server.
`client-secret`	string		Client secret as generated by OIDC server. Used to authenticate this application with the server when requesting JWT based on a code.
`client-timeout-millis`	Duration	`30000`	Timeout of calls using web client.
`cookie-domain`	string		Domain the cookie is valid for. Not used by default.
`cookie-http-only`	boolean	`true`	When using cookie, if set to true, the HttpOnly attribute will be configured. Defaults to `OidcCookieHandler.Builder#DEFAULT_HTTP_ONLY`.
`cookie-max-age-seconds`	long		When using cookie, used to set MaxAge attribute of the cookie, defining how long the cookie is valid. Not used by default.
`cookie-name`	string	`JSESSIONID`	Name of the cookie to use. Defaults to `DEFAULT_COOKIE_NAME`.
`cookie-path`	string	`/`	Path the cookie is valid for. Defaults to "/".
`cookie-same-site`	SameSite (LAX, STRICT, NONE)	`LAX`	When using cookie, used to set the SameSite cookie value. Can be "Strict" or "Lax".
`cookie-secure`	boolean	`false`	When using cookie, if set to true, the Secure attribute will be configured. Defaults to false.
`cookie-use`	boolean	`true`	Whether to use cookie to store JWT between requests. Defaults to `DEFAULT_COOKIE_USE`.
`cors`	CrossOriginConfig		Assign cross-origin resource sharing settings.
`force-https-redirects`	boolean	`false`	Force HTTPS for redirects to identity provider. Defaults to `false`.
`frontend-uri`	string		Full URI of this application that is visible from user browser. Used to redirect request back from identity server after successful login.
`header-token`	TokenHandler		A TokenHandler to process header containing a JWT. Default is "Authorization" header with a prefix "bearer ".
`header-use`	boolean	`true`	Whether to expect JWT in a header field.
`identity-uri`	URI		URI of the identity server, base used to retrieve OIDC metadata.
`introspect-endpoint-uri`	URI		Endpoint to use to validate JWT. Either use this or set #signJwk(JwkKeys) or #signJwk(Resource).
`issuer`	string		Issuer of issued tokens.
`max-redirects`	int	`5`	Configure maximal number of redirects when redirecting to an OIDC provider within a single authentication attempt. Defaults to `DEFAULT_MAX_REDIRECTS`
`oidc-metadata-well-known`	boolean	`true`	If set to true, metadata will be loaded from default (well known) location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. token-endpoint-uri).
`oidc-metadata.resource`	Resource		Resource configuration for OIDC Metadata containing endpoints to various identity services, as well as information about the identity server.
`optional`	boolean	`false`	Whether authentication is required. By default, request will fail if the authentication cannot be verified. If set to true, request will process and this provider will abstain.
`outbound`	OutboundTarget[]		Add a new target configuration.
`propagate`	boolean	`false`	Whether to propagate identity.
`proxy-host`	string		Proxy host to use. When defined, triggers usage of proxy for HTTP requests. Setting to empty String has the same meaning as setting to null - disables proxy.
`proxy-port`	int	`80`	Proxy port. Defaults to `DEFAULT_PROXY_PORT`
`proxy-protocol`	string	`http`	Proxy protocol to use when proxy is used. Defaults to `DEFAULT_PROXY_PROTOCOL`.
`query-param-name`	string	`accessToken`	Name of a query parameter that contains the JWT token when parameter is used.
`query-param-use`	boolean	`false`	Whether to use a query parameter to send JWT token from application to this server.
`redirect`	boolean	`false`	By default the client should redirect to the identity server for the user to log in. This behavior can be overridden by setting redirect to false. When token is not present in the request, the client will not redirect and just return appropriate error response code.
`redirect-attempt-param`	string	`h_ra`	Configure the parameter used to store the number of attempts in redirect. Defaults to `DEFAULT_ATTEMPT_PARAM`
`redirect-uri`	string	`/oidc/redirect`	URI to register web server component on, used by the OIDC server to redirect authorization requests to after a user logs in or approves scopes. Note that usually the redirect URI configured here must be the same one as configured on OIDC server. Defaults to `DEFAULT_REDIRECT_URI`
`relative-uris`	boolean	`false`	Can be set to `true` to force the use of relative URIs in all requests, regardless of the presence or absence of proxies or no-proxy lists. By default, requests that use the Proxy will have absolute URIs. Set this flag to `true` if the host is unable to accept absolute URIs. Defaults to `DEFAULT_RELATIVE_URIS`.
`scope-audience`	string		Audience of the scope required by this application. This is prefixed to the scope name when requesting scopes from the identity server. Defaults to empty string.
`server-type`	string	`@default`	Configure one of the supported types of identity servers. If the type does not have an explicit mapping, a warning is logged and the default implementation is used.
`sign-jwk.resource`	Resource		A resource pointing to JWK with public keys of signing certificates used to validate JWT.
`token-endpoint-auth`	ClientAuthentication (CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, NONE)	`CLIENT_SECRET_BASIC`	Type of authentication to use when invoking the token endpoint. Current supported options: io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication#CLIENT_SECRET_BASIC io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication#CLIENT_SECRET_POST io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication#NONE
`token-endpoint-uri`	URI		URI of a token endpoint used to obtain a JWT based on the authentication code. If not defined, it is obtained from #oidcMetadata(Resource), if that is not defined an attempt is made to use #identityUri(URI)/oauth2/v1/token.
`use-jwt-groups`	boolean	`true`	Claim `groups` from JWT will be used to automatically add groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation).
`validate-jwt-with-jwk`	boolean	`true`	Use JWK (a set of keys to validate signatures of JWT) to validate tokens. Use this method when you want to use default values for JWK or introspection endpoint URI.

Example Code

See the example on GitHub.

Configuration example

security:
  config.require-encryption: false
security:
  providers:
  - oidc:
      client-id: "client-id-of-this-service"
      client-secret: "${CLEAR=client-secret-of-this-service}"
      identity-uri: "http://your-tenant.identity-server.com"
      frontend-uri: "http://my-service:8080"
      audience: "http://my-service"
      cors:
        allow-origins: ["http://foo.com", "http://there.com"]
        allow-methods: ["PUT", "DELETE"]
      outbound:
        - name: "internal-services"
          hosts: ["*.example.org"]
          outbound-token:
            header: "X-Internal-Auth"

Copied

How Does It Work?

At Helidon startup, if OIDC provider is configured, the following will happen:

client-id, client-secret, and identityUri are validated - these must provide values
Unless all resources are configured as local resources, the provider attempts to contact the oidc-metadata.resource endpoint to retrieve all endpoints

At runtime, depending on configuration…

If a request comes without a token or with insufficient scopes:

If redirect is set to true (default), request is redirected to the authorization endpoint of the identity server. If set to false, 401 is returned
User authenticates against the identity server
The identity server redirects back to Helidon service with a code
Helidon service contacts the identity server’s token endpoint, to exchange the code for a JWT
The JWT is stored in a cookie (if cookie support is enabled, which it is by default)
Helidon service redirects to original endpoint (on itself)

Helidon obtains a token from request (from cookie, header, or query parameter):

Token is parsed as a singed JWT
We validate the JWT signature either against local JWK or against the identity server’s introspection endpoint depending on configuration
We validate the issuer and audience of the token if it matches the configured values
A subject is created from the JWT, including scopes from the token
We validate that we have sufficient scopes to proceed, and return 403 if not
Handling is returned to security to process other security providers

CORS Settings

As an experimental feature, you can set up cross-origin handling for the redirect and logout endpoints in an optional cors block inside the oidc configuration.

The table below lists the configuration keys that identify the CORS characteristics.

include::[tag=cors-config-table]

The following example of basic cross-origin configuration limits cross-origin resource sharing for PUT and DELETE operations to only foo.com and there.com:

allow-origins: ["http://foo.com", "http://there.com"]
allow-methods: ["PUT", "DELETE"]

Copied

HTTP Basic Authentication Provider

HTTP Basic authentication support

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-http-auth</artifactId>
</dependency>

Copied

Overview

HTTP Basic Authentication provider

Type: io.helidon.security.providers.httpauth.HttpBasicAuthProvider

Config key

http-basic-auth

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.AuthenticationProvider

Configuration options

Optional configuration options

key	type	default value	description
`optional`	boolean	`false`	Whether authentication is required. By default, request will fail if the authentication cannot be verified. If set to false, request will process and this provider will abstain.
`outbound`	OutboundTarget[]		Add a new outbound target to configure identity propagation or explicit username/password.
`principal-type`	SubjectType (USER, SERVICE)	`USER`	Principal type this provider extracts (and also propagates).
`realm`	string	`helidon`	Set the realm to use when challenging users.
`users`	ConfigUser[]		Set user store to validate users. Removes any other stores added through #addUserStore(SecureUserStore).

Example Code

See the example on GitHub.

Configuration example

security:
  config.require-encryption: false
security:
  providers:
  - http-basic-auth:
      realm: "helidon"
      users:
      - login: "john"
        password: "${CLEAR=password}"
        roles: ["admin"]
      - login: "jack"
        password: "password"
        roles: ["user", "admin"]
      outbound:
        - name: "internal-services"
          hosts: ["*.example.org"]
          # Propagates current user's identity or identity from request property
          outbound-token:
            header: "X-Internal-Auth"
        - name: "partner-service"
          hosts: ["*.partner.org"]
          # Uses this username and password
          username: "partner-user-1"
          password: "${CLEAR=password}"

Copied

How Does It Work?

See https://tools.ietf.org/html/rfc7617.

Authentication of Request

When a request is received without the Authorization: basic …. header, a challenge is returned to provide such authentication.

When a request is received with the Authorization: basic …. header, the username and password is validated against configured users (and users obtained from custom service if any provided).

Subject is created based on the username and roles provided by the user store.

Identity Propagation

When identity propagation is configured, there are several options for identifying username and password to propagate:

We propagate the current username and password (inbound request must be authenticated using basic authentication).
We use username and password from an explicitly configured property (See EndpointConfig.PROPERTY_OUTBOUND_ID and EndpointConfig.PROPERTY_OUTBOUND_SECRET)
We use username and password associated with an outbound target (see example configuration above)

Identity is propagated only if:

There is an outbound target configured for the endpoint
Or there is an explicitly configured username/password for the current request (through request property)

Custom User Store

Java service loader service io.helidon.security.providers.httpauth.spi.UserStoreService can be implemented to provide users to the provider, such as when validated against an internal database or LDAP server. The user store is defined so you never need the clear text password of the user.

Warning on security of HTTP Basic Authenticaton (or lack thereof)

Basic authentication uses base64 encoded username and password and passes it over the network. Base64 is only encoding, not encryption - so anybody that gets hold of the header value can learn the actual username and password of the user. This is a security risk and an attack vector that everybody should be aware of before using HTTP Basic Authentication. We recommend using this approach only for testing and demo purposes.

HTTP Digest Authentication Provider

HTTP Digest authentication support

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-http-auth</artifactId>
</dependency>

Copied

Overview

Http digest authentication security provider

Type: io.helidon.security.providers.httpauth.HttpDigestAuthProvider

Config key

http-digest-auth

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.AuthenticationProvider

Configuration options

Optional configuration options

key	type	default value	description
`algorithm`	Algorithm (MD5)	`MD5`	Digest algorithm to use.
`nonce-timeout-millis`	long	`86400000`	How long will the nonce value be valid. When timed-out, browser will re-request username/password.
`optional`	boolean	`false`	Whether authentication is required. By default, request will fail if the authentication cannot be verified. If set to false, request will process and this provider will abstain.
`principal-type`	SubjectType (USER, SERVICE)	`USER`	Principal type this provider extracts (and also propagates).
`qop`	Qop (NONE, AUTH)	`NONE`	Only `AUTH` supported. If left empty, uses the legacy approach (older RFC version). `AUTH-INT` is not supported.
`realm`	string	`Helidon`	Set the realm to use when challenging users.
`server-secret`	string		The nonce is encrypted using this secret - to make sure the nonce we get back was generated by us and to make sure we can safely time-out nonce values. This secret must be the same for all service instances (or all services that want to share the same authentication). Defaults to a random password - e.g. if deployed to multiple servers, the authentication WILL NOT WORK. You MUST provide your own password to work in a distributed environment with non-sticky load balancing.
`users`	ConfigUser[]		Set user store to obtain passwords and roles based on logins.

Example Code

Configuration example

security:
  config.require-encryption: false
security:
  providers:
  - http-digest-auth:
      realm: "helidon"
      server-secret: "${CLEAR=service-wide-secret-not-known-outside}"
      users:
      - login: "john"
        password: "${CLEAR=password}"
        roles: ["admin"]
      - login: "jack"
        password: "password"
        roles: ["user", "admin"]

Copied

How Does It Work?

See https://tools.ietf.org/html/rfc7616.

Authentication of Request

When a request is received without the Authorization: digest …. header, a challenge is returned to provide such authentication using WWW-Authenticate header.

When a request is received with the Authorization: digest …. header, the request is validated against configured users (and users obtained from custom service if any provided).

Subject is created based on the username and roles provided by the user store.

Custom User Store

Note on security of HTTP Digest Authenticaton

These authentication schemes should be obsolete, though they provide a very easy way to test a protected resource.

Header Authentication Provider

Asserts user or service identity based on a value of a header.

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-header</artifactId>
</dependency>

Copied

Overview

Security provider that extracts a username (or service name) from a header.

Type: io.helidon.security.providers.header.HeaderAtnProvider

Config key

header-atn

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.AuthenticationProvider

Configuration options

Optional configuration options

key	type	default value	description
`atn-token`	TokenHandler		Token handler to extract username from request.
`authenticate`	boolean	`true`	Whether to authenticate requests.
`optional`	boolean	`false`	Whether authentication is required. By default, request will fail if the username cannot be extracted. If set to false, request will process and this provider will abstain.
`outbound`	OutboundTarget[]		Configure outbound target for identity propagation.
`outbound-token`	TokenHandler		Token handler to create outbound headers to propagate identity. If not defined, #atnTokenHandler will be used.
`principal-type`	SubjectType (USER, SERVICE)	`USER`	Principal type this provider extracts (and also propagates).
`propagate`	boolean	`false`	Whether to propagate identity.

Example Code

Configuration example

security:
  providers:
    header-atn:
      atn-token:
        header: "X-AUTH-USER"
      outbound:
        - name: "internal-services"
          hosts: ["*.example.org"]
          # propagates the current user or service id using the same header as authentication
        - name: "partner-service"
          hosts: ["*.partner.org"]
          # propagates an explicit username in a custom header
          username: "service-27"
          outbound-token:
            header: "X-Service-Auth"

Copied

How Does It Work?

This provider inspects a specified request header and extracts the username/service name from it and asserts it as current subject’s principal.

This can be used when we use perimeter authentication (e.g. there is a gateway that takes care of authentication and propagates the user in a header).

Identity Propagation

Identity is propagated only if an outbound target matches the target service.

The following options exist when propagating identity: 1. We propagate the current username using the configured header 2. We use username associated with an outbound target (see example configuration above)

Caution

When using this provider, you must be sure the header cannot be explicitly configured by a user or another service. All requests should go through a gateway that removes this header from inbound traffic, and only configures it for authenticated users/services. Another option is to use this with fully trusted parties (such as services within a single company, on a single protected network not accessible to any users), and of course for testing and demo purposes.

HTTP Signatures Provider

Support for HTTP Signatures

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-http-sign</artifactId>
</dependency>

Copied

Overview

HTTP header signature provider.

Type: io.helidon.security.providers.httpsign.HttpSignProvider

Config key

http-signatures

Copied

This type provides the following service implementations:

io.helidon.security.spi.AuthenticationProvider

Configuration options

Optional configuration options

key	type	default value	description
`backward-compatible-eol`	boolean	`false`	Enable support for Helidon versions before 3.0.0 (exclusive). Until version 3.0.0 (exclusive) there was a trailing end of line added to the signed data. To be able to communicate cross versions, we must configure this when talking to older versions of Helidon. Default value is `false`. In Helidon 2.x, this switch exists as well and the default is `true`, to allow communication between versions as needed.
`headers`	HttpSignHeader[] (SIGNATURE, AUTHORIZATION, CUSTOM)		Add a header that is validated on inbound requests. Provider may support more than one header to validate.
`inbound.keys`	InboundClientDefinition[]		Add inbound configuration. This is used to validate signature and authenticate the party. The same can be done through configuration: <pre> { name = "http-signatures" class = "HttpSignProvider" http-signatures { inbound { # This configures the InboundClientDefinition keys: [ { key-id = "service1" hmac.secret = "${CLEAR=password}" }] } } } </pre>
`optional`	boolean	`true`	Set whether the signature is optional. If set to true (default), this provider will SecurityResponse.SecurityStatus#ABSTAIN from this request if signature is not present. If set to false, this provider will SecurityResponse.SecurityStatus#FAILURE fail if signature is not present.
`outbound`	OutboundConfig		Add outbound targets to this builder. The targets are used to chose what to do for outbound communication. The targets should have OutboundTargetDefinition attached through OutboundTarget.Builder#customObject(Class, Object) to tell us how to sign the request. The same can be done through configuration: <pre> { name = "http-signatures" class = "HttpSignProvider" http-signatures { targets: [ { name = "service2" hosts = ["localhost"] paths = ["/service2/.*"] # This configures the OutboundTargetDefinition signature { key-id = "service1" hmac.secret = "${CLEAR=password}" } }] } } </pre>
`realm`	string	`helidon`	Realm to use for challenging inbound requests that do not have "Authorization" header in case header is HttpSignHeader#AUTHORIZATION and singatures are not optional.
`sign-headers`	HeadersConfig[]		Override the default inbound required headers (e.g. headers that MUST be signed and headers that MUST be signed IF present). Defaults: get, head, delete methods: date, (request-target), host are mandatory; authorization if present (unless we are creating/validating the HttpSignHeader#AUTHORIZATION ourselves put, post: same as above, with addition of: content-length, content-type and digest if present for other methods: date, (request-target) Note that this provider DOES NOT validate the "Digest" HTTP header, only the signature.

Example Code

See the example on GitHub.

Configuration example

security:
  config.require-encryption: false
security:
  providers:
    - http-signatures:
        inbound:
          keys:
            - key-id: "service1-hmac"
              principal-name: "Service1 - HMAC signature"
              hmac.secret: "${CLEAR=somePasswordForHmacShouldBeEncrypted}"
            - key-id: "service1-rsa"
              principal-name: "Service1 - RSA signature"
              public-key:
                keystore:
                  resource.path: "src/main/resources/keystore.p12"
                  passphrase: "password"
                  cert.alias: "service_cert"
        outbound:
          - name: "service2-hmac"
            hosts: ["localhost"]
            paths: ["/service2"]
            signature:
              key-id: "service1-hmac"
              hmac.secret: "${CLEAR=somePasswordForHmacShouldBeEncrypted}"
          - name: "service2-rsa"
            hosts: ["localhost"]
            paths: ["/service2-rsa.*"]
            signature:
              key-id: "service1-rsa"
              private-key:
                keystore:
                  resource.path: "src/main/resources/keystore.p12"
                  passphrase: "password"
                  key.alias: "myPrivateKey"

Copied

Signature Basics

standard: based on https://tools.ietf.org/html/draft-cavage-http-signatures-03
key-id: an arbitrary string used to locate signature configuration - when a request is received the provider locates validation configuration based on this id (e.g. HMAC shared secret or RSA public key). Commonly used meanings are: key fingerprint (RSA); API Key

How Does It Work?

Inbound Signatures We act as a server and another party is calling us with a signed HTTP request. We validate the signature and assume identity of the caller.

Outbound Signatures We act as a client and we sign our outgoing requests. If there is a matching outbound target specified in configuration, its configuration will be applied for signing the outgoing request, otherwise there is no signature added

IDCS Role Mapper

A role mapper to retrieve roles from Oracle IDCS.

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-idcs-mapper</artifactId>
</dependency>

Copied

Single-tenant IDCS Role Mapper

IDCS role mapping provider

Type: io.helidon.security.providers.idcs.mapper.IdcsRoleMapperRxProvider

Config key

idcs-role-mapper

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.SubjectMappingProvider

Configuration options

Optional configuration options

key	type	default value	description
`cache-config`	EvictableCache		Use explicit io.helidon.security.providers.common.EvictableCache for role caching.
`default-idcs-subject-type`	string	`user`	Configure subject type to use when requesting roles from IDCS. Can be either #IDCS_SUBJECT_TYPE_USER or #IDCS_SUBJECT_TYPE_CLIENT. Defaults to #IDCS_SUBJECT_TYPE_USER.
`oidc-config`	OidcConfig		Use explicit io.helidon.security.providers.oidc.common.OidcConfig instance, e.g. when using it also for OIDC provider.
`subject-types`	SubjectType[] (USER, SERVICE)	`USER`	Add a supported subject type. If none added, io.helidon.security.SubjectType#USER is used. If any added, only the ones added will be used (e.g. if you want to use both io.helidon.security.SubjectType#USER and io.helidon.security.SubjectType#SERVICE, both need to be added.

Multi-tenant IDCS Role Mapper

Multitenant IDCS role mapping provider

Type: io.helidon.security.providers.idcs.mapper.IdcsMtRoleMapperRxProvider

Config key

idcs-role-mapper

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.SubjectMappingProvider

Configuration options

Optional configuration options

key	type	default value	description
`cache-config`	EvictableCache		Use explicit io.helidon.security.providers.common.EvictableCache for role caching.
`default-idcs-subject-type`	string	`user`	Configure subject type to use when requesting roles from IDCS. Can be either #IDCS_SUBJECT_TYPE_USER or #IDCS_SUBJECT_TYPE_CLIENT. Defaults to #IDCS_SUBJECT_TYPE_USER.
`idcs-app-name-handler`	TokenHandler		Configure token handler for IDCS Application name. By default the header `IdcsMtRoleMapperRxProvider#IDCS_APP_HEADER` is used.
`idcs-tenant-handler`	TokenHandler		Configure token handler for IDCS Tenant ID. By default the header `IdcsMtRoleMapperRxProvider#IDCS_TENANT_HEADER` is used.
`oidc-config`	OidcConfig		Use explicit io.helidon.security.providers.oidc.common.OidcConfig instance, e.g. when using it also for OIDC provider.
`subject-types`	SubjectType[] (USER, SERVICE)	`USER`	Add a supported subject type. If none added, io.helidon.security.SubjectType#USER is used. If any added, only the ones added will be used (e.g. if you want to use both io.helidon.security.SubjectType#USER and io.helidon.security.SubjectType#SERVICE, both need to be added.

Example code

See the example on GitHub.

Configuration example

security:
  providers:
    - idcs-role-mapper:
        multitenant: false
        oidc-config:
            client-id: "client-id"
            client-secret: "client-secret"
            identity-uri: "IDCS identity server address"

Copied

How does it work?

The provider asks the IDCS server to provide list of roles for the currently authenticated user. The result is cached for a certain period of time (see cache-config above).

ABAC Provider

Attribute-based Access Control (ABAC) authorization provider provides security and authorization service implementations.

Overview

Attribute Based Access Control provider

Type: io.helidon.security.providers.abac.AbacProvider

Config key

abac

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.AuthorizationProvider

Configuration options

Optional configuration options

key	type	default value	description
`fail-if-none-validated`	boolean	`true`	Whether to fail if NONE of the attributes is validated.
`fail-on-unvalidated`	boolean	`true`	Whether to fail if any attribute is left unvalidated.

Maven Dependency

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-abac</artifactId>
</dependency>

Copied

Examples

See the example on GitHub.

Configuration example

security:
  providers:
    - abac:

Copied

Configuration Options

The following table shows all configuration options of the provider and their default values

key	default value	description
`fail-on-unvalidated`	`true`	"Unvalidated" means: an attribute is defined, but there is no validator available for it
`fail-if-none-validated`	`true`	"None validated" means: there was not a single attribute that was validated

Usage

ABAC uses available validators and validates them against attributes of the authenticated user.

Combinations of fail-on-unvalidated and fail-if-none-validated:

true & true: Will fail if any attribute is not validated and if any has failed validation
false & true: Will fail if there is one or more attributes present and NONE of them is validated or if any has failed validation, Will NOT fail if there is at least one validated attribute and any number of not validated attributes (and NONE failed)
false & false: Will fail if there is any attribute that failed validation, Will NOT fail if there are no failed validation or if there are NONE validated

Any attribute of the following objects can be used:

environment (such as time of request) - e.g. env.time.year
subject (user) - e.g. subject.principal.id
subject (service) - e.g. service.principal.id
object (must be explicitly invoked by developer in code, as object cannot be automatically added to security context) - e.g. object.owner

This provider checks that all defined ABAC validators are validated. If there is a definition for a validator that is not checked, the request is denied (depending on configuration as mentioned above).

ABAC provider also allows an object to be used in authorization process, such as when evaluating if an object’s owner is the current user. The following example uses the Expression language validator to demonstrate the point in a JAX-RS resource:

Example of using an object

@Authenticated
@Path("/abac")
public class AbacResource {
  @GET
  @Authorized(explicit = true)
  @PolicyStatement("${env.time.year >= 2017 && object.owner == subject.principal.id}")
  public Response process(@Context SecurityContext context) {
      // probably looked up from a database
      SomeResource res = new SomeResource("user");
      AuthorizationResponse atzResponse = context.authorize(res);

      if (atzResponse.isPermitted()) {
          //do the update
          return Response.ok().entity("fine, sir").build();
      } else {
          return Response.status(Response.Status.FORBIDDEN)
                  .entity(atzResponse.getDescription().orElse("Access not granted"))
                  .build();
      }
  }
}

Copied

The following validators are implemented:

Role Validator

Checks whether user/service is in either of the required role(s).

Configuration Key: role-validator

Annotations: @RolesAllowed, @RoleValidator.Roles

Configuration example for WebServer

security:
  web-server.paths:
    - path: "/user[/{*}]"
      roles-allowed: ["user"]

Copied

JAX-RS example

@RolesAllowed("user")
@RoleValidator.Roles(value = "service_role", subjectType = SubjectType.SERVICE)
@Authenticated
@Path("/abac")
public class AbacResource {
}

Copied

Interaction with JAX-RS Sub-Resource Locators

When using sub-resource locators in JAX-RS, the roles allowed are collected from each "level" of execution: - Application class annotations - Resource class annotations + resource method annotations - Sub-resource class annotations + sub-resource method annotations - Sub-resource class annotations + sub-resource method annotations (for every sub-resource on the path)

The RolesAllowed or Roles annotation to be used is the last one in the path as defined above.

Example 1: There is a RolesAllowed("admin") defined on a sub-resource locator resource class. In this case the required role is admin.

Example 2: There is a RolesAllowed("admin") defined on a sub-resource locator resource class and a RolesAllowed("user") defined on the method of the sub-resource that provides the response. In this case the required role is user.

Scope Validator

Checks whether user has all the required scopes.

Configuration Key: scope-validator

Annotations: @Scope

Configuration example for WebServer

security:
  web-server.paths:
    - path: "/user[/{*}]"
      abac.scopes:
        ["calendar_read", "calendar_edit"]

Copied

JAX-RS example

@Scope("calendar_read")
@Scope("calendar_edit")
@Authenticated
@Path("/abac")
public class AbacResource {
}

Copied

Expression Language Policy Validator

Policy executor using Java EE policy expression language (EL)

Configuration Key: policy-javax-el

Annotations: @PolicyStatement

Example of a policy statement: ${env.time.year >= 2017}

Configuration example for WebServer

security:
  web-server.paths:
    - path: "/user[/{*}]"
      policy:
        statement: "hasScopes('calendar_read','calendar_edit') AND timeOfDayBetween('8:15', '17:30')"

Copied

JAX-RS example

@PolicyStatement("${env.time.year >= 2017}")
@Authenticated
@Path("/abac")
public class AbacResource {
}

Copied

Google Login Provider

Authenticates a token from request against Google identity provider

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-google-login</artifactId>
</dependency>

Copied

Overview

Google Authentication provider

Type: io.helidon.security.providers.google.login.GoogleTokenProvider

Config key

google-login

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.AuthenticationProvider

Configuration options

Optional configuration options

key	type	default value	description
`client-id`	string		Google application client id, to validate that the token was generated by Google for us.
`optional`	boolean	`false`	If set to true, this provider will return io.helidon.security.SecurityResponse.SecurityStatus#ABSTAIN instead of failing in case of invalid request.
`outbound`	OutboundConfig		Outbound configuration - a set of outbound targets that will have the token propagated.
`proxy-host`	string		Set proxy host when talking to Google.
`proxy-port`	int	`80`	Set proxy port when talking to Google.
`realm`	string	`helidon`	Set the authentication realm to build challenge, defaults to "helidon".
`token`	TokenHandler	`Authorization` header with `bearer` prefix	Token provider to extract Google access token from request, defaults to "Authorization" header with a "bearer " prefix.

Example Code

See the example on GitHub.

Configuration example

security:
  providers:
    - provider:
        client-id: "Google client id"

Copied

How Does It Work?

We expect to receive a token (with sufficient scopes) from the inbound request, such as when using the Google login button on a page. The page has access to the token in javascript and can send it to backend with every request in a header field (Authorization with `bearer ` prefix is assumed by default).

After we receive the token in Helidon, we parse it and:

Validate if it timed out locally
Return a cached response (see EvictableCache with default values)
Otherwise verify using Google API - GoogleIdTokenVerifier

We build a subject from the Google token with the following attributes filled (if present in the token):

userId
email
name
emailVerified
locale
family_name
given_name
picture (URL)

Outbound Security: The token will be propagated to outbound calls if an outbound target exists that matches the invoked endpoint (see outbound configuration above).

JWT Provider

JWT token authentication and outbound security provider

Setup

Maven dependency

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-jwt</artifactId>
</dependency>

Copied

Overview

JWT authentication provider

Type: io.helidon.security.providers.jwt.JwtProvider

Config key

jwt

Copied

This type provides the following service implementations:

io.helidon.security.spi.SecurityProvider
io.helidon.security.spi.AuthenticationProvider

Configuration options

Optional configuration options

key	type	default value	description
`allow-impersonation`	boolean	`false`	Whether to allow impersonation by explicitly overriding username from outbound requests using EndpointConfig.PROPERTY_OUTBOUND_ID property. By default this is not allowed and identity can only be propagated.
`allow-unsigned`	boolean	`false`	Configure support for unsigned JWT. If this is set to `true` any JWT that has algorithm set to `none` and no `kid` defined will be accepted. Note that this has serious security impact - if JWT can be sent from a third party, this allows the third party to send ANY JWT and it would be accpted as valid.
`atn-token.handler`	TokenHandler		Token handler to extract username from request.
`atn-token.jwk.resource`	Resource		JWK resource used to verify JWTs created by other parties.
`atn-token.jwt-audience`	string		Audience expected in inbound JWTs.
`atn-token.verify-signature`	boolean	`true`	Configure whether to verify signatures. Signatures verification is enabled by default. You can configure the provider not to verify signatures. <b>Make sure your service is properly secured on network level and only accessible from a secure endpoint that provides the JWTs when signature verification is disabled. If signature verification is disabled, this service will accept <i>ANY</i> JWT</b>
`authenticate`	boolean	`true`	Whether to authenticate requests.
`optional`	boolean	`false`	Whether authentication is required. By default, request will fail if the username cannot be extracted. If set to false, request will process and this provider will abstain.
`principal-type`	SubjectType (USER, SERVICE)	`USER`	Principal type this provider extracts (and also propagates).
`propagate`	boolean	`true`	Whether to propagate identity.
`sign-token`	OutboundConfig		Configuration of outbound rules.
`sign-token.jwk.resource`	Resource		JWK resource used to sign JWTs created by us.
`sign-token.jwt-issuer`	string		Issuer used to create new JWTs.
`use-jwt-groups`	boolean	`true`	Claim `groups` from JWT will be used to automatically add groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation).

Example Code

See the example on GitHub.

Configuration example

security:
  providers:
    - provider:
        atn-token:
          jwk.resource.resource-path: "verifying-jwk.json"
          jwt-audience: "http://my.service"
        sign-token:
          jwk.resource.resource-path: "signing-jwk.json"
          jwt-issuer: "http://my.server/identity"
          outbound:
          - name: "propagate-token"
            hosts: ["*.internal.org"]
          - name: "generate-token"
            hosts: ["1.partner-service"]
            jwk-kid: "partner-1"
            jwt-kid: "helidon"
            jwt-audience: "http://1.partner-service"

Copied

How Does It Work?

JSON Web Token (JWT) provider has support for authentication and outbound security.

Authentication is based on validating the token (signature, valid before etc.) and on asserting the subject of the JWT subject claim.

For outbound, we support either token propagation (e.g. the token from request is propagated further) or support for generating a brand new token based on configuration of this provider.

Contents

Implemented Security Providers

OIDC Provider

Setup

Configuration options

Example Code

How Does It Work?

CORS Settings

HTTP Basic Authentication Provider

Setup

Overview

Configuration options

Example Code

How Does It Work?

HTTP Digest Authentication Provider

Setup

Overview

Configuration options

Example Code

How Does It Work?

Header Authentication Provider

Setup

Overview

Configuration options

Example Code

How Does It Work?

HTTP Signatures Provider

Setup

Overview

Configuration options

Example Code

Signature Basics

How Does It Work?

IDCS Role Mapper

Setup

Single-tenant IDCS Role Mapper

Configuration options

Multi-tenant IDCS Role Mapper

Configuration options

Example code

How does it work?

ABAC Provider

Overview

Configuration options

Maven Dependency

Examples

Configuration Options

Usage

Role Validator

Interaction with JAX-RS Sub-Resource Locators

Scope Validator

Expression Language Policy Validator

Google Login Provider

Setup

Overview

Configuration options

Example Code

How Does It Work?

JWT Provider

Setup

Overview

Configuration options

Example Code

How Does It Work?