@toa.io/extensions.exposition 1.0.0-alpha.278 → 1.0.0-alpha.282

package/documentation/identity.md

@@ -54,10 +54,33 @@ The `Token` is the **primary** authentication scheme.
 If request originators use an alternative authentication scheme, they will receive a response
 containing `Token` credentials and will be required to switch to the `Token` scheme for any
 subsequent requests.
-Continued use of other authentication schemes will result in temporary blocking of requests.
 
 See [`identity.tokens` component](components.md#local-tokens).
 
+### Failed authentications
+
+Credentials that are rejected can be metered per client address, whatever the scheme. An address
+may fail `attempts` at once and earns them back at `attempts` per `interval` seconds; a request
+carrying credentials from an address with nothing left is answered `429 Too Many Requests` with
+`Retry-After`. Nothing is metered unless the exposition annotation carries `bouncer`;
+`attempts` and `interval` default to 20 and 60. The address is the one the request context
+resolved, see [Client address](ip.md): `bouncer` requires `ip`, in the same environment, and a
+request without an address is not metered.
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  ip: cf-connecting-ip
+  bouncer:
+    attempts: 20
+    interval: 60
+```
+
+The count is shared by the gateway replicas through
+[atomicity](../../../connectors/atomicity/readme.md) and decided in each process; nothing is read on
+the request path.
+
 ### Bearer scheme
 
 OpenID tokens issued by trusted providers.
@@ -85,13 +108,15 @@ configuration:
         aud: <APPLE_CLIENT_ID>
         secret: <APPLE_CLIENT_SECRET> # enables Authorization Code Flow
     principal:
+      authority: example
       iss: https://accounts.google.com
       sub: 4218230498234
     assert: true
 ```
 
-`principal` specifies the values of the `iss` and `sub` claims of an Identity that will be granted
-with a `system` role.
+`principal` specifies the authority and the values of the `iss` and `sub` claims of an Identity
+that will be granted with a `system` role. The same subject in another authority is ordinary
+credentials.
 
 `assert` indicates whether the Identity should be implicitly created when valid credentials for a
 non-existent Identity are provided (default `true`).
@@ -113,8 +138,8 @@ iss: code issuer
 for: redirect URI
 ```
 
-Trust configuration for the issuer requires `aud` and either `secret` or `signature`
-values to enable the Authorization Code Flow.
+Trust configuration for the issuer requires either `secret` or `signature`
+to enable the Authorization Code Flow.
 
 > If `aud` is an array, the first value is used.
 
@@ -159,13 +184,15 @@ GET /identity/ HTTP/1.1
 authentication: OTP dXNlcm5hbWU6MTIzNDU2
 ```
 
-OTP expiration time can be configured using the `identity.otp` configuration.
+OTP expiration time and the number of failed attempts a username is allowed within it can be
+configured using the `identity.otp` configuration.
 
 ```yaml
 # context.toa.yaml
 configuration:
   identity.otp:
     lifetime: 60 # seconds
+    attempts: 5
 ```
 
 ## Identity inception
@@ -223,6 +250,11 @@ Identity `2428c31ecb6e4a51a24ef52f0c4181b9` are created.
 
 Inception is supported for `Basic` and `Bearer` authentication schemes.
 
+Inception goes ahead when the request carries no credentials, or credentials the scheme verified
+and no Identity owns, which its `authenticate` operation reports as `NOT_FOUND`. Credentials
+rejected for any other reason, a wrong password for one, are answered with `401 Unauthorized`
+before the endpoint is called.
+
 ## Identity assertion
 
 `auth:assert` directive is used to ensure that given credentials are associated with an existing

package/documentation/io.md

@@ -97,8 +97,8 @@ and reports what it could not the next time it gets through.
 What a request is metered against. Give one, or a list — a list keys on the combination, so
 `[route, ip]` meters each address separately on each route.
 
-- `ip` — the client address, read from `X-Forwarded-For` where it is set and not private,
-  and from the connection otherwise.
+- `ip` — the client address, as the request context resolved it. See [Client address](ip.md) for
+  where it is read from and why.
 - `path` — the path the request came in on, `/users/1`.
 - `route` — the route as declared, `/users/:id`. Every path matching the route shares one budget,
   which `path` cannot do: keyed on `path`, walking ids is a way around the limit.

package/documentation/ip.md

@@ -0,0 +1,24 @@
+# Client address
+
+The address a request comes from is resolved once, into the request context, and read from there
+by whatever keys on it: the meter of [failed authentications](identity.md#failed-authentications)
+and the `ip` key of [`io:throttle`](io.md#key-components).
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  ip: cf-connecting-ip
+```
+
+`ip` names the header the address is read from. In production the gateway sits behind a load
+balancer, an ingress or a CDN: the connection it accepts comes from that machine, so every client
+shares one address and nothing tells them apart. The edge is the one that saw the client connect,
+and it writes the client's address into a header of its own, `CF-Connecting-IP`, `X-Real-IP` or
+`X-Forwarded-For`, depending on the infrastructure. A client may send any of these headers too, so
+the gateway trusts none of them on its own: the deployment names the one its edge overwrites, and
+where the header holds a list, the last value is the one the edge appended.
+
+The connection's address is never used. Without `ip`, or for a request that does not carry the
+header, the request has no address: the bouncer and a throttle keyed on `ip` let it through and
+say so in the log, once per hundred seconds rather than once per request.

package/documentation/passkeys.md

@@ -3,3 +3,9 @@
 - [Standard](https://www.w3.org/TR/webauthn-2/)
 - [Features](../features/passkeys.feature)
 - [Credential management](credentials.md#passkeys)
+
+## Origin
+
+The relying party is the client. The origin a passkey is registered under, and the RP ID derived
+from it, come from the request, so a passkey belongs to the origin of the client that registered
+it, and a client on another origin does not see it.

package/features/auth.assert.feature

@@ -41,7 +41,7 @@ Feature: Identity assertion
       authorization: Token ${{ user.token }}
       """
 
-    # invalid credentials
+    # wrong password for the credentials just created
     When the following request is received:
       """
       GET /echo/ HTTP/1.1
@@ -51,7 +51,5 @@ Feature: Identity assertion
       """
     Then the following reply is sent:
       """
-      422 Unprocessable Entity
-
-      code: INVALID_PASSWORD
+      401 Unauthorized
       """

package/features/auth.claims.feature

@@ -9,6 +9,7 @@ Feature: Federated identity authentication
       """yaml
       trust:
         - iss: http://localhost:44444
+          aud: test
       """
 
   Scenario: Full claim

package/features/auth.incept.feature

@@ -118,3 +118,49 @@ Feature: Identity inception
       id: ${{ identity.id }}
       foo: bar
       """
+
+  Scenario: Inception with a wrong password for existing credentials
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     | _version |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+    And the `users` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          POST:
+            io:input: [name]
+            io:output: true
+            incept: id
+            query: ~
+            endpoint: transit
+      """
+    # developer:wrong
+    When the following request is received:
+      """
+      POST /users/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      accept: application/yaml
+      content-type: application/yaml
+
+      name: Bill Smith
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+    # a token that does not decrypt
+    When the following request is received:
+      """
+      POST /users/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token garbage
+      accept: application/yaml
+      content-type: application/yaml
+
+      name: Bill Smith
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """

package/features/authorities.feature

@@ -30,3 +30,42 @@ Feature: Authorities
       """
       200 OK
       """
+
+  Scenario: Rejecting a malformed authority
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        GET:
+          dev:stub: Hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: zzz,identity==abc,authority==q
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+      """
+
+  Scenario: Matching an authority regardless of case
+    Given the annotation:
+      """yaml
+      authorities:
+        example: the.example.com
+      /:
+        anonymous: true
+        GET:
+          map:authority: authority
+          dev:stub: Hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: The.Example.COM
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """

package/features/authorities.federation.feature

@@ -7,6 +7,7 @@ Feature: OIDC tokens with authorities
       """yaml
       trust:
         - iss: http://localhost:44444
+          aud: test
       """
 
 

package/features/identity.bans.feature

@@ -135,3 +135,66 @@ Feature: Bans
       """
       401 Unauthorized
       """
+
+  Scenario: Banning an Identity revokes its custom tokens
+    Given the `identity.roles` database contains:
+      | _id                              | identity                         | role                 |
+      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | system:identity:bans |
+    And the `identity.keys` database is empty
+    And the `identity.tokens` configuration:
+      """yaml
+      cache:
+        ttl: 1
+      """
+    When the following request is received:
+      """
+      POST /identity/tokens/e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjoxMjM0NQ==
+      accept: application/yaml
+      content-type: application/yaml
+
+      label: Forever token
+      lifetime: 0
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      token: ${{ token }}
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    When the following request is received:
+      """
+      PUT /identity/bans/e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      content-type: application/yaml
+
+      banned: true
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    # the key is revoked eventually, and the runtime forgets it after `cache.ttl`
+    Then after 2 seconds
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """

package/features/identity.basic.feature

@@ -88,7 +88,7 @@ Feature: Basic authentication
       200 OK
       """
 
-    # username is taken
+    # username is taken: a wrong password for existing credentials is refused before the call
     When the following request is received:
       """
       POST /users/ HTTP/1.1
@@ -101,7 +101,7 @@ Feature: Basic authentication
       """
     Then the following reply is sent:
       """
-      409 Conflict
+      401 Unauthorized
       """
 
     # credentials already exists
@@ -246,7 +246,9 @@ Feature: Basic authentication
   Scenario: Granting a `system` role to a Principal
     Given the `identity.basic` configuration:
       """yaml
-      principal: root
+      principal:
+        authority: nex
+        username: root
       """
     And the annotation:
       """yaml
@@ -321,6 +323,64 @@ Feature: Basic authentication
       message: Principal username cannot be changed
       """
 
+  Scenario: Principal username in another authority is ordinary credentials
+    Given the `identity.basic` configuration:
+      """yaml
+      principal:
+        authority: nex
+        username: root
+      """
+    And the annotation:
+      """yaml
+      /:
+        io:output: true
+        GET:
+          auth:role: system:stub
+          dev:stub:
+            access: granted!
+      """
+    When the following request is received:
+      """
+      POST /identity/basic/ HTTP/1.1
+      host: the.other.com
+      accept: application/yaml
+      content-type: application/yaml
+
+      username: root
+      password: secret#1234
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      id: ${{ id }}
+      """
+    Then after 0.1 seconds
+    When the following request is received:
+      """
+      GET /identity/roles/${{ id }}/ HTTP/1.1
+      host: the.other.com
+      authorization: Basic cm9vdDpzZWNyZXQjMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      []
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: the.other.com
+      authorization: Basic cm9vdDpzZWNyZXQjMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
   Scenario: Creating an Identity using inception with existing credentials
     Given the `users` is running with the following manifest:
       """yaml
@@ -528,3 +588,35 @@ Feature: Basic authentication
 
       id: ${{ identity.id }}
       """
+
+  Scenario: Password containing colons
+    When the following request is received:
+      """
+      POST /identity/basic/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/yaml
+
+      username: colon
+      password: pa:ss:word
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      id: ${{ id }}
+      """
+    # colon:pa:ss:word
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic Y29sb246cGE6c3M6d29yZA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: ${{ id }}
+      """

package/features/identity.feature

@@ -87,3 +87,154 @@ Feature: Identity resource
       """
       401 Unauthorized
       """
+
+  Scenario: Authenticating with a scheme named after an object property
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Constructor abc
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: __proto__ abc
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: Failing authentication repeatedly
+    Given the annotation:
+      """yaml
+      ip: x-real-ip
+      bouncer:
+        attempts: 2
+        interval: 60
+      """
+    # developer:wrong
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      x-real-ip: 203.0.113.9
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      x-real-ip: 203.0.113.9
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+    # the address has spent its attempts, and earns one back in interval / attempts seconds
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      x-real-ip: 203.0.113.9
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      429 Too Many Requests
+      retry-after: 30
+      """
+    # a request without credentials is not metered
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      """
+
+  Scenario: Failing authentication behind a trusted proxy
+    Given the annotation:
+      """yaml
+      ip: x-real-ip
+      bouncer:
+        attempts: 1
+        interval: 60
+      """
+    # developer:wrong
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      x-real-ip: 203.0.113.1
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      x-real-ip: 203.0.113.1
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      429 Too Many Requests
+      """
+    # another address, as the proxy reports it
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      x-real-ip: 203.0.113.2
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: Failing authentication without a client address
+    Given the annotation:
+      """yaml
+      ip: x-real-ip
+      bouncer:
+        attempts: 1
+        interval: 60
+      """
+    # the header the address is read from is not sent, so nothing is metered
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOndyb25n
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """

package/features/identity.federation.feature

@@ -10,6 +10,7 @@ Feature: Identity Federation
       """yaml
       trust:
         - iss: http://localhost:44444
+          aud: test
       """
     And the IDP token for User is issued
     When the following request is received:
@@ -75,6 +76,7 @@ Feature: Identity Federation
       """yaml
       trust:
         - iss: http://localhost:44444
+          aud: test
       assert: false
       """
     Given the `users` is running with the following manifest:
@@ -170,7 +172,9 @@ Feature: Identity Federation
       """yaml
       trust:
         - iss: http://localhost:44444
+          aud: test
       principal:
+        authority: nex
         iss: http://localhost:44444
         sub: root
       """
@@ -218,6 +222,7 @@ Feature: Identity Federation
       """yaml
       trust:
         - iss: http://localhost:44444
+          aud: test
       """
     And the `identity.basic` database is empty