Module io.helidon.security
Package io.helidon.security

Interface Security

public interface Security
This class is used to "bootstrap" security and integrate it with other frameworks; runtime main entry point is SecurityContext.

It is possible to configure it manually using builder() or use create(Config) to initialize using configuration support.

Security is constructed from various providers SecurityProvider and a selection policy ProviderSelectionPolicy to choose the right one(s) to secure a request.

See Also:

  • Field Details

    • HEADER_ORIG_URI

      static final String HEADER_ORIG_URI
      Integration should add a special header to each request. The value will contain the original URI as was issued - for HTTP this is the relative URI including query parameters.
      See Also:

  • Method Details

    • create

      static Security create(Config config)
      Creates new instance based on configuration values.
      Parameters:
      config - Config instance located on security configuration ("providers" is an expected child)
      Returns:
      new instance.

    • builder

      static Security.Builder builder(Config config)
      Creates new instance based on configuration values.
      Parameters:
      config - Config instance located on security configuration ("providers" is an expected child)
      Returns:
      new instance.

    • builder

      static Security.Builder builder()
      Creates Security.Builder class.
      Returns:
      builder

    • getRoles

      static Set<String> getRoles(Subject subject)
      Get a set of roles the subject has, based on Role. This is the set of roles as assumed by authentication provider. Authorization providers may use a different set of roles (and context used authorization provider to check SecurityContext.isUserInRole(String)).
      Parameters:
      subject - Subject of a user/service
      Returns:
      set of roles the user/service is in

    • serverTime

      SecurityTime serverTime()
      Time that is decisive for the server. This usually returns accessor to current time in a specified time zone.

      SecurityTime may be configured to a fixed point in time, intended for testing purposes.

      Returns:
      time to access current time for security decisions

    • contextBuilder

      SecurityContext.Builder contextBuilder(String id)
      Create a new security context builder to build and instance. This is expected to be invoked for each request/response exchange that may be authenticated, authorized etc. Context holds the security subject... Once your processing is done and you no longer want to keep security context, call SecurityContext.logout() to clear subject and principals.
      Parameters:
      id - to use when logging, auditing etc. (e.g. some kind of tracing id). If none or empty, security instance UUID will be used (at least to map all audit records for a single instance of security component). If defined, security will prefix this id with security instance UUID
      Returns:
      new fluent API builder to create a SecurityContext

    • createContext

      SecurityContext createContext(String id)
      Create a new security context with the defined id and all defaults.
      Parameters:
      id - id of this context
      Returns:
      new security context

    • tracer

      Tracer tracer()
      Returns a tracer that can be used to construct new spans.
      Returns:
      Tracer, may be a no-op tracer if tracing is disabled

    • customAnnotations

      Collection<Class<? extends Annotation>> customAnnotations()
      Get the complete set of annotations expected by (all) security providers configured. This is to be used for integration with other frameworks that support annotations.
      Returns:
      Collection of annotations expected by configured providers.

    • configFor

      Config configFor(String child)
      The configuration of security.

      This method will NOT return security internal configuration:

      • provider-policy
      • providers
      • environment
      Parameters:
      child - the name of the child node to retrieve from config
      Returns:
      a child node of security configuration
      Throws:
      IllegalArgumentException - in case you request child in one of the forbidden trees

    • encrypt

      String encrypt(String configurationName, byte[] bytesToEncrypt)
      Encrypt bytes. This method handles the bytes in memory, and as such is not suitable for processing of large amounts of data.
      Parameters:
      configurationName - name of the configuration of this encryption
      bytesToEncrypt - bytes to encrypt
      Returns:
      future with cipher text

    • decrypt

      byte[] decrypt(String configurationName, String cipherText)
      Decrypt cipher text. This method handles the bytes in memory, and as such is not suitable for processing of large amounts of data.
      Parameters:
      configurationName - name of the configuration of this encryption
      cipherText - cipher text to decrypt
      Returns:
      future with decrypted bytes

    • digest

      String digest(String configurationName, byte[] bytesToDigest, boolean preHashed)
      Create a digest for the provided bytes.
      Parameters:
      configurationName - name of the digest configuration
      bytesToDigest - data to digest
      preHashed - whether the data is already a hash
      Returns:
      future with digest (such as signature or HMAC)

    • digest

      String digest(String configurationName, byte[] bytesToDigest)
      Create a digest for the provided raw bytes.
      Parameters:
      configurationName - name of the digest configuration
      bytesToDigest - data to digest
      Returns:
      future with digest (such as signature or HMAC)

    • verifyDigest

      boolean verifyDigest(String configurationName, byte[] bytesToDigest, String digest, boolean preHashed)
      Verify a digest.
      Parameters:
      configurationName - name of the digest configuration
      bytesToDigest - data to verify a digest for
      digest - digest as provided by a third party (or another component)
      preHashed - whether the data is already a hash
      Returns:
      future with result of verification (true means the digest is valid)

    • verifyDigest

      boolean verifyDigest(String configurationName, byte[] bytesToDigest, String digest)
      Verify a digest.
      Parameters:
      configurationName - name of the digest configuration
      bytesToDigest - raw data to verify a digest for
      digest - digest as provided by a third party (or another component)
      Returns:
      future with result of verification (true means the digest is valid)

    • secret

      Optional<String> secret(String configurationName)
      Get a secret.
      Parameters:
      configurationName - name of the secret configuration
      Returns:
      future with the secret value, or error if the secret is not configured

    • secret

      String secret(String configurationName, String defaultValue)
      Get a secret.
      Parameters:
      configurationName - name of the secret configuration
      defaultValue - default value to use if secret not configured
      Returns:
      future with the secret value

    • environmentBuilder

      SecurityEnvironment.Builder environmentBuilder()
      Security environment builder, to be used to create environment for evaluating security in integration components.
      Returns:
      builder to build SecurityEnvironment

    • subjectMapper

      Optional<SubjectMappingProvider> subjectMapper()
      Subject mapping provider used to map subject(s) authenticated by AuthenticationProvider to a new Subject, e.g. to add roles.
      Returns:
      subject mapping provider to use or empty if none defined

    • enabled

      boolean enabled()
      Whether security is enabled or disabled. Disabled security does not check authorization and authenticates all users as SecurityContext.ANONYMOUS.
      Returns:
      true if security is enabled

    • audit

      void audit(String tracingId, AuditEvent event)
      Audit an event.
      Parameters:
      tracingId - id to map this audit event to a request
      event - event to audit

    • providerSelectionPolicy

      ProviderSelectionPolicy providerSelectionPolicy()
      Configured provider selection policy.
      Returns:
      provider selection policy

    • resolveAtnProvider

      Optional<? extends AuthenticationProvider> resolveAtnProvider(String providerName)
      Find an authentication provider by name, or use the default if the name is not available.
      Parameters:
      providerName - name of the provider
      Returns:
      authentication provider if the named one is configured, or a default one is configured, otherwise empty

    • resolveAtzProvider

      Optional<AuthorizationProvider> resolveAtzProvider(String providerName)
      Find an authorization provider by name, or use the default if the name is not available.
      Parameters:
      providerName - name of the provider
      Returns:
      authorization provider if the named one is configured, or a default one is configured, otherwise empty

    • resolveOutboundProvider

      List<? extends OutboundSecurityProvider> resolveOutboundProvider(String providerName)
      Find outbound provider(s) by name, or use the default if the name is not available.
      Parameters:
      providerName - name of the provider
      Returns:
      outbound providers to use