Skip to content
Permalink
Browse files

SSO/SAML docs and auth config (#59)

* SSO initial page and okta example

Signed-off-by: Zach Hill <zach@anchore.com>

* Adds sso updates and examples for keycloak as well as general oauth api docs and credential storage docs

Signed-off-by: Zach Hill <zach@anchore.com>

* Adds more sso examples and docs coverage of credential storage cofnig, and identity mappings

Signed-off-by: Zach Hill <zach@anchore.com>
  • Loading branch information...
zhill committed Sep 3, 2019
1 parent 9953a72 commit 1f7652fccfdc642de5ed318ee748286e89dbf585
@@ -0,0 +1,71 @@
---
title: "Configuring User Credential Storage"
linkTitle: "Configuring User Credential Storage"
weight: 4
---

## Overview

When using the Anchore internal DB to manage user identities (external management is optional in the Enterprise version), all user information is stored in
the Anchore DB. The credentials can be stored plaintext in the DB, which allows efficient usage internally for dev/test systems, or the credentials can be
stored in hashed form using the Argon2 hashing algorithm.

Hashed passwords are much more secure, but are expensive to compare and cannot be used for internal service communication since they cannot be reversed. Anchore
provides a token based authentication mechanism as well (a simplified Password-Grant flow of Oauth2) to mitigate the performance issue, but it requires that
all Anchore services be deployed with a shared secret in the configuration or a public/private keypair common to all services.

## Passwords

The configuration of how passwords are stored is set in the `user_authentication` section of the _config.yaml_ file and *must* be consistent across all components of an Anchore Engine deployment. Mismatch
in this configuration between components of the system will result in the system not being able to communicate internally.

```
user_authentication:
hashed_passwords: true|false
```

By default, `hashed_passwords` is set to `false`. This supports upgrade from previous versions of Anchore as well as usage for installations without a shared key or public/private keys for Anchore. When oauth
is not configured in the system, Anchore must be able to use HTTP Basic authentication between internal services and thus requires credentials that can be read.

## Bearer Tokens/OAuth2

If Anchore is configured to support bearer tokens, the tokens are generated and returned to the user but never persisted in the database. All tokens expire, and currently
Anchore does not support refresh tokens, upon expiration a user must re-authenticate with the username and password to get a new token. Users must still have password credentials, however.
Password persistence and protection configuration still applies as in the Password section above.

## Configuring Hashed Passwords and OAuth

NOTE: password storage configuration must be done at the time of deployment, it cannot be modified at runtime or after installation with an existing DB since
it will invalidate all existing credentials, including internal system credentials and the system will not be functional. You must choose the mechanism
at system deployment time.

Set in _config.yaml_ for all components of the deployment:

Option 1: Use a shared secret for signing/verifying oauth tokens

user_authentication:
oauth:
enabled: true
hashed_passwords: true
keys:
secret: mysecretvalue

Option 2: Use a public/private key pair, delivered as pem files on the filesystem of the containers anchore runs in:

user_authentication:
oauth:
enabled: true
hashed_passwords: true
keys:
private_key_path: <path to private key pem file>
public_key_path: <path to public key pem file>

Using environment variables with the _config.yaml_ bundled into the Anchore provided anchore-engine image is also an option.
NOTE: These are *only* valid when using the _config.yaml_ provided in the image due to that file referencing them explicitly as replacement values.

ANCHORE_AUTH_SECRET = the string to use as a secret
ANCHORE_AUTH_PUBKEY = path to public key file
ANCHORE_AUTH_PRIVKEY = path to the private key file
ANCHORE_OAUTH_ENABLED = boolean to enable/disable oauth support
ANCHORE_OAUTH_TOKEN_EXPIRATION = the integer value to set number of seconds a token should be valid (default is 3600/1 hr)
ANCHORE_AUTH_ENABLE_HASHED_PASSWORDS = boolean to enable/disable hashed password storage in the anchore db instead of clear text

This file was deleted.

@@ -0,0 +1,109 @@
---
title: "Supported Authentication Modes"
linkTitle: "Authentication Modes"
weight: 4
---

## Anchore Engine Authentication Overview

Anchore Engine supports two ways for users to authenticate to the API: HTTP Basic and Bearer Tokens. HTTP Basic is always
supported but Bearer token auth must be explicitly configured to be used.

For production installation, it is recommended to [configure bearer tokens as well as hashed password storage]({{< ref "/docs/engine/engine_installation/configuration/user_credential_storage" >}})
in the db to ensure that no clear text password is present anywhere in the system. Because the system uses credentials for
internal service-to-service communication, it is required that if hashing passwords is configured that oauth also be enabled
to allow inter-service communication using service-generated tokens.

This will require providing a shared secret across all components or a pair of public/private keys. Each service must have
exactly the same secret or key-pair present.


### Basic Auth

By default, Anchore Engine uses [HTTP Basic](https://tools.ietf.org/html/rfc2617) auth for all internal and external API
operations. For production deployments with this mode, it is critical to use HTTPS to secure the communication channel
between services and users. See: [Configuring HTTPS]({{< ref "/docs/engine/engine_installation/configuration/tls_ssl_config" >}}) for setup information.

Example Usage:

[root@4a1b1d9105a8 ~]# curl -v -u admin:foobar http://localhost:8228/v1/accounts
* About to connect() to localhost port 8228 (#0)
* Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8228 (#0)
* Server auth using Basic with user 'admin'
> GET /v1/accounts HTTP/1.1
> Authorization: Basic YWRtaW46Zm9vYmFy
> User-Agent: curl/7.29.0
> Host: localhost:8228
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: TwistedWeb/19.2.1
< Date: Wed, 28 Aug 2019 20:18:15 GMT
< Content-Type: application/json
< Content-Length: 195
<
[
{
"created_at": "2019-08-28T07:32:39Z",
"email": "admin@myanchore",
"last_updated": "2019-08-28T07:32:39Z",
"name": "admin",
"state": "enabled",
"type": "admin"
}
]
### Bearer Tokens/Oauth

When configured, anchore implements the Oauth2 Password grant flow. Anchore is configured with a default 'anonymous' client
id that is used to avoid requiring registering specific clients.

Required payload, must be www-form-urlencoded:

grant_type=password
username=<user>
password=<password>
client_id=anonymous

The payload is sent using HTTP POST to the _/v1/oauth/token_ endpoint. The returned token is valid until expiration (typically 1 hour)
and is used by sending it in the _Authorization_ header as a bearer token:

Example usage:


root@4a1b1d9105a8 ~]# curl -v -d 'grant_type=password&client_id=anonymous&username=admin&password=foobar' -X POST http://localhost:8228/v1/oauth/token
* About to connect() to localhost port 8228 (#0)
* Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8228 (#0)
> POST /v1/oauth/token HTTP/1.1
> User-Agent: curl/7.29.0
> Host: localhost:8228
> Accept: */*
> Content-Length: 70
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 70 out of 70 bytes
< HTTP/1.1 200 OK
< Server: TwistedWeb/19.2.1
< Date: Wed, 28 Aug 2019 20:14:32 GMT
< Content-Type: application/json
< Cache-Control: no-store
< Pragma: no-cache
< Content-Length: 332
<
* Connection #0 to host localhost left intact
{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhbmNob3JlLWVuZ2luZSIsInN1YiI6IjRhYjQ3NzczOTQ0MjRkM2RiNmY1MTczMzU1ZjE3YTZhIiwiZXhwIjoxNTY3MDI2ODcyLCJpYXQiOjE1NjcwMjMyNzIsImp0aSI6IjFmMzhjOWUwZmQ2YzQyZTJiNWRlZmU2NTU2NGU3MzE5In0.dxpW3k5OFn5_CGD2_GIeJ6KO2hWMVZqh4adoqPj8t7g", "expires_in": 3600, "token_type": "Bearer"}
root@4a1b1d9105a8 ~]# curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhbmNob3JlLWVuZ2luZSIsInN1YiI6IjRhYjQ3NzczOTQ0MjRkM2RiNmY1MTczMzU1ZjE3YTZhIiwiZXhwIjoxNTY3MDI3NTEyLCJpYXQiOjE1NjcwMjM5MTIsImp0aSI6IjMzY2I1NTA1NjU3ZDRkZjBhYzY2MWE5Yjk3NWEyYjJmIn0.nQkkZ17lU_UeWVuVAt2RlLJ-mY935bP6OV3R1fBL_24" http://localhost:8228/v1/account
{
"created_at": "2019-08-28T07:32:39Z",
"email": "admin@myanchore",
"last_updated": "2019-08-28T07:32:39Z",
"name": "admin",
"state": "enabled",
"type": "admin"
}
[root@4a1b1d9105a8 ~]#

0 comments on commit 1f7652f

Please sign in to comment.
You can’t perform that action at this time.