AWS

Sign in with AWS accounts¶

AWS offers two different products for signing users in, and they reach Mewbo along different paths. Pick the one your users already live in.

• IAM Identity Center, formerly AWS SSO, is the enterprise workforce directory. In practice it is a SAML identity provider paired with SCIM provisioning. Use it when your organisation already manages workforce identity in AWS.
• Amazon Cognito is a user-pool service aimed at application sign-in. It speaks OpenID Connect and puts group membership in a cognito:groups claim. Use it when Mewbo's users live in a pool you control rather than in your corporate directory.

IAM Identity Center¶

Identity Center does not offer a general-purpose OIDC relying-party registration for third-party applications. The supported integration is a custom SAML application, optionally with SCIM provisioning alongside it.

Prerequisites, including one your users will notice¶

Mewbo's SAML limitations apply here unchanged. The Entra guide's SAML prerequisites carry all four with the reasoning behind each, and its reverse-proxy section is the way out if request signing or the redirect restriction blocks you.

One thing is specific to this portal. Clicking the Mewbo tile in the AWS access portal will not sign anyone in, because sign-in must start at Mewbo, at /api/auth/saml/login. Point the tile there, or tell users where to start.

The login flow¶

sequenceDiagram
    autonumber
    participant B as Browser
    participant M as Mewbo API
    participant I as IAM Identity Center

    B->>M: GET /api/auth/saml/login
    M-->>B: 302 to Identity Center + signed state cookie
    B->>I: AuthnRequest
    I->>I: Sign-in and multi-factor
    I-->>B: POST SAMLResponse back
    B->>M: POST /api/auth/saml/acs
    M->>M: Validate signature, audience, expiry
    M->>M: Map attributes, provision, resolve roles
    M-->>B: 302 to return_to + session cookie

Configure Identity Center¶

Create a custom SAML 2.0 application. Mewbo publishes its own SP metadata, so hand the AWS console this document rather than transcribing values.

https://console.example.com/api/auth/saml/metadata

If you enter values by hand, these are the two.

Then configure the attribute mappings. Identity Center sends nothing beyond the subject by default, so map at minimum an email attribute, a display name, and a groups attribute if you want group-driven roles.

Configure Mewbo¶

{
  "api": {
    "auth": {
      "enabled": true,
      "authenticators": [
        {
          "name": "identity-center",
          "kind": "saml",
          "issuer": "https://portal.sso.eu-west-1.amazonaws.com/saml/assertion/EXAMPLEID",
          "sp_entity_id": "https://console.example.com",
          "idp_metadata_url": "https://portal.sso.eu-west-1.amazonaws.com/saml/metadata/EXAMPLEID",
          "subject_attribute": "NameID",
          "email_attribute": "email",
          "name_attribute": "displayName",
          "groups_attribute": "groups"
        }
      ],
      "session": { "secret": "generate-a-long-random-string" },
      "role_mappings": {
        "default_role": "viewer",
        "rules": [
          { "match": "MewboAdmins", "target": "admin" },
          { "match": "Engineering", "target": "operator" }
        ]
      },
      "bootstrap": { "admin_group": "MewboAdmins" }
    }
  }
}

issuer must match the assertion's issuer exactly. Exactly one of idp_metadata_url or idp_metadata_xml is required, and both or neither is rejected when the configuration is parsed.

groups_attribute must match the attribute name you configured on the AWS side. SAML attribute names are frequently full URIs rather than short names, so copy them from the AWS console rather than guessing.

The saml extra is required. Run pip install mewbo-iam[saml].

SCIM provisioning¶

Identity Center can push users and groups into Mewbo over SCIM 2.0, so accounts appear before their first login and are deactivated when someone leaves. What the endpoint implements, what it refuses and how deletes behave is covered once in SCIM provisioning. This section is the AWS wiring.

Enable it in Mewbo¶

"scim": {
  "enabled": true,
  "secret": "a-long-random-bearer-secret-you-generate"
}

The token is the raw secret, not a signed or derived value. Whatever you set as secret is exactly what Identity Center presents as Authorization: Bearer <secret>. Generate something long and random and treat it as a credential. The config API marks it write-only, so it is never returned once set.

There is no token lifecycle. No mint endpoint, no expiry, no rotation window. Rotating means changing it in both places at once, so plan a brief window where provisioning fails.

Give AWS these values¶

What the endpoint supports¶

All routes are mounted under /api/scim/v2, and every response, errors included, is application/scim+json.

Pagination uses startIndex, starting at 1, and count, capped at 200. Point a connector's discovery step at /ServiceProviderConfig, since there are no /Schemas or /ResourceTypes endpoints for it to probe.

Two behaviours are worth knowing before you point Identity Center at this. SCIM fails closed, so with no secret configured every request returns 401. While SCIM is off, every route returns a clean 404 without touching a store or comparing a token, which makes mounting it safe even if you never turn it on.

Amazon Cognito¶

Cognito is a standards-clean OIDC provider. The only thing to know is where it puts groups.

Configure Cognito¶

Create a user pool and an app client with a client secret.

Configure Mewbo¶

{
  "name": "cognito",
  "kind": "oidc",
  "issuer": "https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_ExamplePool",
  "discovery_url": "https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_ExamplePool/.well-known/openid-configuration",
  "client_id": "the-app-client-id",
  "client_secret": "the-app-client-secret",
  "scopes": ["openid", "email", "profile"],
  "groups_claim": "cognito:groups"
}

The claim name genuinely contains a colon, and that is fine. The dotted-path reader splits on . only, so cognito:groups is read as one top-level claim name rather than as a path.

The issuer is the user pool's URL, with no trailing slash and no /oauth2 suffix. It must match the iss claim exactly.

The oidc extra is required. Run pip install mewbo-iam[oidc].

The 25-group quota¶

Cognito applies a default quota of 25 groups per user pool. It is an AWS-side soft quota you can request an increase for, and it shapes how you model authorization.

With at most 25 groups to spend across every application sharing the pool, do not mirror your organisational structure into Cognito groups. Create a few coarse groups that mean something to Mewbo, such as mewbo-admins, mewbo-operators and mewbo-viewers, and map those.

Unlike Entra, Cognito never substitutes a pointer when a user is in many groups, so there is no overage failure mode here. The quota bites at group creation time instead, which is far easier to notice.

Verify it works¶

1. Sign in, then call GET /api/auth/me. Expect authenticated: true, your subject, the resolved roles, the full permissions set, and an auth_method object reporting kind: "saml" or kind: "oidc" with your issuer.
2. If roles shows only the default on the Cognito path, confirm the user is in a group and that groups_claim reads cognito:groups exactly, colon included.
3. If roles shows only the default on the Identity Center path, check the attribute mapping first. Identity Center sends very little unless you tell it to.
4. To check SCIM, call GET /api/scim/v2/ServiceProviderConfig with your bearer token. It returns the capability document, which is the quickest confirmation that the token and the endpoint URL are both right.

Failure modes¶

These are AWS specific. Boot failures and generic callback errors are in the shared Troubleshooting table.

Choosing between them¶

For the concepts behind this page, including roles, the permission catalogue, how a request resolves to a principal, and what is and is not enforced, see Authentication and Access. This guide connects one provider. It deliberately does not restate the model.