DOCSEARCHbyAlgolia
Submit Docs

Mujina Documentation

repository·main·Indexed 18 days ago

https://github.com/openconext/mujina

A configurable SAML2 Identity Provider (IdP) and Service Provider (SP) built with OpenSAML and Java Spring Boot. Designed for testing SAML-based middleware like SURFconext, Mujina allows both the IdP and SP to be reconfigured at runtime via a REST API. As of version 9.0.0, it requires Java 21 and Maven 3.

Tokens
2.5K
Snippets
11
Records
16
Agent score
14%

What's inside Mujina

  1. What is Mujina?

    main

    Mujina is a configurable SAML2 Identity Provider (IdP) and Service Provider (SP) built with OpenSAML and Java Spring Boot. It is primarily used to test the SURFconext middleware.

    Key characteristics:

    • Both IdP and SP can be reconfigured at runtime via a REST API.
    • As of version 9.0.0, it requires Java 21.
    • It runs as a standalone Spring Boot application (not using Tomcat).

  2. Build Mujina from source

    main

    To build Mujina, you need Maven 3 and Java 21. The build dependencies are hosted at https://build.openconext.org/repository/public/ and are fetched automatically by Maven during the build process.

    git clone git@github.com:OpenConext/Mujina.git
cd Mujina
mvn clean install

  3. Generate and configure private signing keys and certificates

    main

    Mujina's SAML Spring Security library requires a private key and public certificate pair for both the Identity Provider (IdP) and the Service Provider (SP).

    1. Generate the key pair using OpenSSL:
    openssl req -subj '/O=Organization, CN=Mujina/' -newkey rsa:2048 -new -x509 -days 3652 -nodes -out mujina.crt -keyout mujina.pem
    1. Reformat the private key to pkcs8 DER format for Java KeyStore compatibility:
    openssl pkcs8 -nocrypt -in mujina.pem -topk8 -out mujina.der
    1. Clean the files: Remove whitespace, headings, and footers from the .crt and .der files to get a single-line string.

    On Linux:

    cat mujina.der |head -n -1 |tail -n +2 | tr -d '\n'; echo
cat mujina.crt |head -n -1 |tail -n +2 | tr -d '\n'; echo

    On macOS (requires coreutils via brew install coreutils):

    cat mujina.der |ghead -n -1 |tail -n +2 | tr -d '\n'; echo
cat mujina.crt |ghead -n -1 |tail -n +2 | tr -d '\n'; echo
    1. Update application.yml: Add the cleaned strings to the configuration.
    idp:
  private_key: ${output from cleaning the der file}
  certificate: ${output from cleaning the crt file}

sp:
  private_key: ${output from cleaning the der file}
  certificate: ${output from cleaning the crt file}

  4. Run the Service Provider (SP)

    main

    To start the Mujina Service Provider, open a new terminal session, navigate to the mujina-sp directory, and run the Maven Spring Boot plugin. By default, the application is accessible at http://localhost:9090/.

    Accessing the SP will typically redirect you to the IdP for authentication. You can use the default credentials admin / secret to log in.

    cd mujina-sp
mvn spring-boot:run

  5. Run the Identity Provider (IdP)

    main

    To start the Mujina Identity Provider, navigate to the mujina-idp directory and use the Maven Spring Boot plugin. By default, the application is accessible at http://localhost:8080/.

    cd mujina-idp
mvn spring-boot:run

  6. Default Identity Provider (IdP) configuration

    main

    The following settings are applied by default to the IdP:

    • Entity ID: http://mock-idp
    • Signature Algorithm: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
    • Default Users:
      • admin / secret (Roles: ROLE_USER, ROLE_ADMIN)
      • user / secret (Role: ROLE_USER)
    • Default Attributes (stored as lists):
      • urn:mace:dir:attribute-def:uid: john.doe
      • urn:mace:dir:attribute-def:cn: John Doe
      • urn:mace:dir:attribute-def:givenName: John
      • urn:mace:dir:attribute-def:sn: Doe
      • urn:mace:dir:attribute-def:displayName: John Doe
      • urn:mace:dir:attribute-def:mail: j.doe@example.com
      • urn:mace:terena.org:attribute-def:schacHomeOrganization: example.com
      • urn:mace:dir:attribute-def:eduPersonPrincipalName: j.doe@example.com
    • Signing: A default certificate and private key are provided.
    • ACS Endpoint: By default, the ACS endpoint is expected to be provided by the SP in the AuthnRequest. However, if you set the ACS endpoint via the IdP REST API, it will override the value in the AuthnRequest.

  7. Default Service Provider (SP) configuration

    main

    The following settings are applied by default to the SP:

    • Entity ID: http://mock-sp
    • Signature Algorithm: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
    • Signing: A default certificate and private key are provided.

  8. Change signing credentials (Certificate and Key)

    main

    This API is available on both the IDP and the SP.

    Requirements:

    • The certificate must be in PEM format.
    • The key must be in base64 encoded pkcs6 DER format.

    Example usage using environment variables:

    export CERT="...PEM_CONTENT..."
export KEY="...BASE64_PKCS6_DER_CONTENT..."
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X POST -d "{\"certificate\": \"$CERT\",\"key\":\"$KEY\"}" \
        http://localhost:8080/api/signing-credential

  9. Change the entityID

    main

    This API is available on both the IDP and the SP. Use it to update the entity identifier.

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X PUT -d "myEntityId" \
        http://localhost:8080/api/entityid

  10. Manage SAML attributes on the IDP

    main

    The following APIs are available only on the IDP. Note that attributes are always handled as lists.

    Set a global attribute

    Sets an attribute value for all users.

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X PUT -d '["bar"]' \
        http://localhost:8080/api/attributes/urn:mace:dir:attribute-def:foo

    Set an attribute for a specific user

    Sets an attribute for a specific existing user. The user must already exist.

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X PUT -d '["bar"]' \
        http://localhost:8080/api/attributes/urn:mace:dir:attribute-def:foo/user

    Remove an attribute

    Global:

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X DELETE \
        http://localhost:8080/api/attributes/urn:mace:dir:attribute-def:foo

    For a specific user:

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X DELETE \
        http://localhost:8080/api/attributes/urn:mace:dir:attribute-def:foo/user

  11. Set the Signature Algorithm

    main

    This API is available on both the IDP and the SP. It allows you to specify the XML digital signature algorithm to be used.

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X PUT -d "http://www.w3.org/2000/09/xmldsig#rsa-sha1" \
        http://localhost:9090/api/signatureAlgorithm

  12. Configure Authentication Method on the IDP

    main

    This API is available only on the IDP. It controls how authentication is handled.

    Possible values:

    • USER: Requires a valid user to be known in Mujina's IdP.
    • ALL: Accepts any username and password combination. As a side effect, the urn:mace:dir:attribute-def:uid attribute is set to the username upon login.

    This is also configurable in application.yml via auth_method: USER or auth_method: ALL.

    curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -X PUT -d "ALL" \
        http://localhost:8080/api/authmethod