diff --git a/Readme.md b/Readme.md index fd781e7..63deec2 100644 --- a/Readme.md +++ b/Readme.md @@ -10,51 +10,156 @@ To learn more about Platform SSO (PSSO), please visit https://twocanoes.com/sso. psso-server-go should be able to be deployed on macOS, Windows, and Linux. PSSO requires that the service use TLS with a public SSL certificate (Let's Encrypt works fine). The basic steps are: 1. Install Go and Git on your target platform -2. Register a DNS name and get a certificate from a well known authority + +2. Register a DNS name and get a certificate from a well known authority. Make sure the private key and certificate are in PEM format and are not password protected. Copy the private key to /etc/psso/privkey.pem and the certificate chain to /etc/psso/fullchain.pem. The server certificate should listed first and the root certificate in the chain listed last in the fullchain.pem. 3. Clone the repo to the target machine: `git clone https://github.com/twocanoes/psso-server-go` - + 4. Run go mod tidy to get the required packages: - + `go mod tidy` -5. Run the app. The defaults assume a folder writeable by the app /var/psso. The defaults are set for macOS and Linux and should be modified as outlined in the Modifying Defaults section. +5. Run the app. The defaults assume a folder writeable by the app /var/psso. The defaults are set for macOS and Linux and should be modified as outlined in the Modifying Defaults section. Set the PSSO\_ISSUER to the hostname of the service. It must match the Issuer in the configuration profile below. - go run cmd/local/main.go + PSSO\_ISSUER=idp.twocanoes.com go run cmd/local/main.go -6. Create a configuration profile and SSOE app in macOS to use this service. Please see https://twocanoes.com/sso for further information. +6. If the hostname is not accessible via DNS on the client, add the hostname and the IP address to the /etc/hosts file, replacing idp.example.com with the hostname of the PSSO server. +> sudo echo "idp.example.com 192.168.1.100" \>\> /etc/hosts + +6. On the client, verify these endpoints are accessible (replace idp.example.com with your hostname) and do not have any SSL errors. +http://idp.example.com/.well-known/apple-app-site-association +https://idp.example.com/.well-known/jwks.json + +6. Install Scissors test app from: + +> https://github.com/twocanoes/sso/releases/ + +6. Create a configuration profile and SSOE app in macOS to use this service. Replace the following key/values: + +* AccountDisplayName: name of the Identity Provider that will show in dialogs. For example, "My Identity Provider". +* BaseURL: The URL of the service. For example, https://idp.example.com. +* Issuer: the hostname. It must match the issuer when running. For example, idp.example.com. +* ```xml + + +~ + +PayloadContent + + + AuthenticationMethod + Password + ExtensionIdentifier + com.twocanoes.Scissors.ssoe + PayloadDisplayName + Single Sign-On Extensions Scissors + PayloadIdentifier + com.apple.extensiblesso.CA351D35-96B1-41CF-B25B-DF3273189AAD + PayloadOrganization + + PayloadType + com.apple.extensiblesso + PayloadUUID + 4B7148CD-1069-4140-95CE-78F61BCD9C2B + PayloadVersion + 1 + PlatformSSO + + AccountDisplayName + My Identity Provider + AuthenticationMethod + Password + EnableAuthorization + + EnableCreateUserAtLogin + + NewUserAuthorizationMode + Groups + UseSharedDeviceKeys + + UserAuthorizationMode + Groups + + TeamIdentifier + UXP6YEHSPW + Type + Redirect + + + BaseURL + https://idp.example.com/ + Issuer + idp.example.com + Audience + idp-audience + ClientID + idp-clientid + PayloadDisplayName + Scissors SSOE + PayloadIdentifier + mdscentral.00A38C42-503B-4016-A86D-2186CDA5989C.com.twocanoes.xcreds.3E7FAF27-6179-46AA-B1A3-B55E08D3273D + PayloadOrganization + + PayloadType + com.twocanoes.Scissors.ssoe + PayloadUUID + 3E7FAF27-6179-46AA-B1A3-B55E08D3273D + PayloadVersion + 1 + + +PayloadDisplayName +PSSO +PayloadIdentifier +mdscentral.00A38C42-503B-4016-A86D-2186CDA5989C +PayloadOrganization + +PayloadScope +System +PayloadType +Configuration +PayloadUUID +851A1B56-6A8A-442B-91CB-BC12FF416766 +PayloadVersion +1 + + +``` ## Modifying Defaults Set up the environment variables for the service configuration: -_PSSO_ISSUER_ (example.com): Issuer. Used for Iss in JWT. +_PSSO\_ISSUER_ Issuer (required, no default value. Usually URL to IdP like https://idp.twocanoes.com). Used for Iss in JWT. Must match the Issuer key in the config profile for the sample app "Scissors" or issuer in ASAuthorizationProviderExtensionLoginConfiguration as shown below: + +> let config = ASAuthorizationProviderExtensionLoginConfiguration(clientID:clientID , issuer: *issuer*, tokenEndpointURL: tokenEndpoint, jwksEndpointURL: jwksEndpoint, audience: audience) + -_PSSO_AUDIENCE_ (psso): Audience. Used for Aud in JWT. +_PSSO\_AUDIENCE_ (psso): Audience. Used for Aud in JWT. -_PSSO_ADDRESS_ (:6443): Network address and port to listen on. +_PSSO\_ADDRESS_ (:6443): Network address and port to listen on. -_PSSO_JWKSFILEPATH_ (/var/psso/jwks.json): Path to JSON file where the service keys will be created and stored. +_PSSO\_JWKSFILEPATH_ (/var/psso/jwks.json): Path to JSON file where the service keys will be created and stored. -_PSSO_TLSPRIVATEKEYPATH_ (/etc/psso/privkey.pem): Path to TLS certificate in PEM format. +_PSSO\_TLSPRIVATEKEYPATH_ (/etc/psso/privkey.pem): Path to TLS certificate in PEM format. -_PSSO_TLSCERTIFICATECHAINPATH_ (/etc/psso/fullchain.pem): Path to folder where device keys are stored. Each registered device will be in its own file in this folder. +_PSSO\_TLSCERTIFICATECHAINPATH_ (/etc/psso/fullchain.pem): Path to folder where device keys are stored. Each registered device will be in its own file in this folder. -_PSSO_DEVICEFILEPATH_: /var/psso/devices): Path to folder where device keys +_PSSO\_DEVICEFILEPATH_: /var/psso/devices): Path to folder where device keys -_PSSO_NONCEPATH_: /var/psso/nonce): Path to folder where nonce are stored. Each nonce will be in its own file in this folder. +_PSSO\_NONCEPATH_: /var/psso/nonce): Path to folder where nonce are stored. Each nonce will be in its own file in this folder. -_PSSO_KEYPATH_ (/var/psso/keys): Path to folder where device keys are stored. Each device key will be in its own file in this folder. This file is used to look up the device file when a key id is given. +_PSSO\_KEYPATH_ (/var/psso/keys): Path to folder where device keys are stored. Each device key will be in its own file in this folder. This file is used to look up the device file when a key id is given. -_PSSO_ENDPOINTNONCE_ (/psso/nonce): HTTP endpoint where the client requests a nonce. +_PSSO\_ENDPOINTNONCE_ (/psso/nonce): HTTP endpoint where the client requests a nonce. -_PSSO_ENDPOINTREGISTER_ (/psso/register): HTTP endpoint where client registers a new device +_PSSO\_ENDPOINTREGISTER_ (/psso/register): HTTP endpoint where client registers a new device -_PSSO_ENDPOINTTOKEN_ (/psso/token): HTTP token where client posts JWT tokens +_PSSO\_ENDPOINTTOKEN_ (/psso/token): HTTP token where client posts JWT tokens -_PSSO_ENDPOINTJWKS_ (/psso/.well-known/jwks.json): HTTP endpoint for advertising the public key for the PSSO service. +_PSSO\_ENDPOINTJWKS_ (/psso/.well-known/jwks.json): HTTP endpoint for advertising the public key for the PSSO service. ## Thanks