includes.security.providers.http-signatures.adoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of helidon-docs
The newest version!
///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2020, 2024 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

ifndef::rootdir[:rootdir: {docdir}/../../..]

=== HTTP Signatures Provider
:description: Helidon Security HTTP Signatures Provider
:keywords: helidon, security
:feature-name: HTTP Signatures Security Provider

Support for HTTP Signatures.

==== Setup

[source,xml]
.Maven dependency
----

    io.helidon.security.providers
    helidon-security-providers-http-sign

----

==== Overview

include::{rootdir}/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc[leveloffset=+2,tag=config]


==== Example code

See the link:{helidon-github-examples-url}/security/webserver-signatures[example] on GitHub.

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

==== 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