Page History

...

• Services that only communicate within the Docker network.
• Example: MockAS, MongoDB, APIgw
• Not accessible from outside the docker network.

...

• Services are exposed to the local machine but do not need internet connectivity.
• Example: Jaeger, UI
• Accessible within the host system and the local network, unless prevented by, e.g., firewall rules.

...

• Services that must be reachable from the public internet.
• Example: SATOSA, SimpleSAMLphp
• Required for authentication and credential issuance.

...

...

SATOSA Authentication Flow

The SimpleSAMLphp service acts as a SAMLIdP, handling authentication requests from SATOSA. To function correctly, SATOSA must retrieve metadata from SimpleSAMLphp to determine how authentication should be performed.

...

When SATOSA starts, it must fetch metadata from SimpleSAMLphp. By default, the metadata is retrieved from:

...

This metadata contains essential details, including authentication endpoints where SATOSA must redirect users. SimpleSAMLphp generates this metadata based on how it is accessed—specifically, the hostname and port that SATOSA uses to connect.

SATOSA does not modify this metadata but relies on it as-is for authentication redirections.

...

After retrieving metadata, SATOSA follows this process to authenticate users:

1. User Initiates Authentication

   • A user attempts to access a SATOSA-protected endpoint.

2. SATOSA Redirects to SimpleSAMLphp

   • SATOSA reads its metadata to determine the correct Single Sign-On (SSO) URL.
   • The user’s browser is redirected to SimpleSAMLphp for authentication.

3. User Authenticates with SimpleSAMLphp

   • The user enters their credentials.
   • If authentication is successful, SimpleSAMLphp generates a SAML assertion and redirects the user back to SATOSA.

4. SATOSA Processes the Authentication Response

   • SATOSA validates the SAML assertion.
   • If valid, SATOSA completes authentication and grants access to the user.

Importance of Consistent Hostname and Port Configuration

Since SATOSA retrieves metadata from SimpleSAMLphp, the authentication redirect URL is determined by this metadata.

If the hostname or port used during metadata retrieval differs from the one required during redirection, authentication will fail due to incorrect redirects.

How to Prevent Issues:

• The same hostname and port must be used for internal and external access.
  • Correct Example:
    • SATOSA fetches metadata from https://simplesamlphp.example.com:8443
    • SATOSA also redirects users to https://simplesamlphp.example.com:8443 during authentication.

By ensuring that SATOSA always retrieves metadata using the same hostname that external users will use, authentication flows correctly and avoids unnecessary failures.

...

Cloning the Repository

Clone the vc_up_and_running repository from GitHub: 

git clone git@github.com:dc4eu/vc_up_and_running.git
cd vc_up_and_running

...

Explanation of .env Variables

General Configuration

• TAG=0.5.17
  Specifies the version tag of the deployed Docker images.

• DOCKERHUB_FQDN=docker.sunet.se
  Docker registry URL for pulling images.

• NETWORK_NAME=dc4eu_shared_network
  The name of the Docker network that all containers use for internal communication.

API Gateway

• APIGW_HOST_PORT=8080
  The port mapped to the host for accessing the API Gateway.

• APIGW_HOST=apigw.example.com
  The FQDN for the API Gateway.

• APIGW_URL=http://apigw.example.com:8080
  The full URL where ApiGW is accessible.
  Important: The API Gateway uses HTTP, not HTTPS.

Issuer (SATOSA)

• ISSUER_HOST=issuer.example.com
  The FQDN of the SATOSA issuer service.

• ISSUER_URL=https://issuer.example.com:8000
  The full URL where the issuer service is accessible externally.

SimpleSAMLphp (SAML IdP)

• SAML_IDP_HOST=simplesamlphp.example.com
  The FQDN of the SimpleSAMLphp identity provider.
  Important: This hostname must be the same internally in Docker and externally, otherwise, SATOSA will generate incorrect authentication redirection URLs.

• SAML_MD_URL=https://simplesamlphp.example.com:8443/simplesaml/saml2/idp/metadata.php
  The URL where SATOSA retrieves SAML metadata from SimpleSAMLphp.

  • This URL is used both internally (inside Docker) and externally.
  • The hostname and port in this URL must match the actual external service.
  • If the internal hostname or port differs, authentication redirects will fail.

• SAML_DS_URL=https://ds.example.com
  The Discovery Service (DS) URL.

  • This is only used if the internal SAML IdP is not used and
  • The metadata (SAML_MD_URL) contains multiple IdPs.
  • If set, users will be presented with a choice of IdPs for authentication.

Jaeger Tracing

• JAEGER_HOST_PORT=16686
  The port mapped to the host for Jaeger, used for monitoring and tracing.

Credential Offer

• CREDENTIAL_OFFER_URL=https://dc4eu.wwwallet.org/cb
  The callback URL where credentials are offered to wallets.

...

Configuration Guidelines

• Ensure hostnames are correctly set

  • If external access is needed, hostnames must be set to real FQDNs.
  • Internal hostnames must match the metadata configuration (e.g., SAML_MD_URL).

• Ensure required ports are open and properly mapped

  • SATOSA (8000) and SimpleSAMLphp (8443) must be accessible externally.
  • API Gateway (8080) operates on HTTP and does not require external access.

...

Running the Setup Script

The start.sh script initializes the environment, generates the required keys and certificates, and starts the necessary services.

...

The script performs the following setup tasks:

• Creates the required Docker network if it does not already exist.
• Generates private keys for credential signing.
• Creates SAML certificates for SATOSA and SimpleSAMLphp.
• Extracts SAML metadata from SATOSA, ensuring that SimpleSAMLphp is correctly configured.
• Starts all required services by launching Docker containers with docker-compose.

This ensures that all necessary configurations are in place before the system starts running.

...