From 7307871ca76543735cbf1740af5bdf373856787c Mon Sep 17 00:00:00 2001 From: victor-chaparro Date: Wed, 21 Aug 2024 14:47:31 -0600 Subject: [PATCH] Added documentation for newly supported auth types and working with keys. --- .../docs/onboarding-users/transport/rest.md | 38 +++++++++-- .../transport/working-with-keys.md | 66 +++++++++++++++++++ 2 files changed, 98 insertions(+), 6 deletions(-) create mode 100644 prime-router/docs/onboarding-users/transport/working-with-keys.md diff --git a/prime-router/docs/onboarding-users/transport/rest.md b/prime-router/docs/onboarding-users/transport/rest.md index 18dbd8d0ac2..0c15b3527f6 100644 --- a/prime-router/docs/onboarding-users/transport/rest.md +++ b/prime-router/docs/onboarding-users/transport/rest.md @@ -23,14 +23,15 @@ For authentication, you need to do both step a and step b.
  1. Generate the "Credential in JSON format" for authentication
    2. -Currently, RESTTransport uses the one of the three options: +Currently, RESTTransport uses the one of the following options: i) UserPass, - ii) UserApiKey with JKS, or + ii) UserApiKey with JKS iii) UserApiKey with two-legged credential type to authenticate and obtain Bearer token from STLT. -User can use **primeCLI** command with credential-create option to generate the "Credential in JSON format" as given below. + iv) UserJks +User can use the **primeCLI** command with credential-create option to generate the "Credential in JSON format" as given below. -- With STLT's credential username and password given to us by STLT, user needs to run the following command to generate the UserPass credential type object: +- With STLT's credential username and password given to us by the STLT, user needs to run the following command to generate the UserPass credential type object: Command: ./prime credential-create --type UserPass --user --pass @@ -118,9 +119,9 @@ The receiver's RESTTransport includes the following fields: }" type: "REST" - c) See UserApiKey+Tow-legged RESTTransport setting Example below: + c) See UserApiKey+Two-legged RESTTransport setting Example below: - FLEXION--ETOR-SERVICE-RECEIVER uses UserApiKey + Tow-legged authentication type: + FLEXION--ETOR-SERVICE-RECEIVER uses UserApiKey + Two-legged authentication type: ================================================================================ transport: ! reportUrl: "https://sample.net/v1/etor/orders" @@ -139,6 +140,31 @@ The receiver's RESTTransport includes the following fields: sourceLabName: "CDC PRIME REPORTSTREAM" type: "REST" + d) See UserApiKey without OAuth RESTTransport setting Example below: + + FLEXION--ETOR-SERVICE-RECEIVER uses UserApiKey + ================================================================================ + transport: ! + reportUrl: "https://sample.net/v1/etor/orders" + authType: "apiKey" + tlsKeystore: null + headers: + Content-Type: "elims/json" + type: "REST" + + e) See JKS without OAuth RESTTransport setting Example below: + + CA-DPH--FULL-ELR-REST-JKS uses UserJKS + ================================================================================ + transport: ! + reportUrl: "https://sample.net/v1/etor/orders" + authType: "jks" + tlsKeystore: "jks" + tlsKeystore: "CA-DPH--FULL-ELR-REST-JKS" + headers: + Content-Type: "text/plain" + type: "REST" + ## 4. Final Step is to test/check the receiver's REST transport is connected successfully Now that you have completed/created REST Transport setting please do the following: - Create PR - which includes the receiver's setting code diff --git a/prime-router/docs/onboarding-users/transport/working-with-keys.md b/prime-router/docs/onboarding-users/transport/working-with-keys.md new file mode 100644 index 00000000000..9ec12cc09f6 --- /dev/null +++ b/prime-router/docs/onboarding-users/transport/working-with-keys.md @@ -0,0 +1,66 @@ +### Working with Keys + +#### Introduction +Each STLT has a unique configuration for server authentication. This documentation provides examples of how we've configured keys to successfully authenticate with different STLTs. + +### Public/Private Key Pair +Most STLTs use public/private key pairs for authentication. Here's how to generate and configure these keys: + +1. **Generate a PEM file:** + This command creates a PEM file containing both a private and public key: + ```bash + openssl genrsa -out my_rsa_private_key.pem 2048 + ``` + +2. **Extract the Public Key:** + To extract the public key from the PEM file and share it with the STLT, run the following command: + ```bash + ssh-keygen -y -f my_rsa_private_key.pem > my_rsa_public_key.pub + ``` + +3. **Convert PEM to PPK:** + The PEM file needs to be converted into a PPK file and stored in Azure for ReportStream authentication. Use this command to convert the file: + ```bash + puttygen my_rsa_private_key.pem -o my_rsa_private_key.ppk + ``` +4. **Create ReportStream Credential:** + Use the primeCLI create-credential command to store the ppk file in JSON to be able to store it in Azure so that ReportStream can use it. + ```bash + ./prime create-credential --type UserPpk --ppk-file /Users/vic/Downloads/texas/tx_rsa_private_key.ppk + ``` + +### STLT generates Public/Private key pair +Sometimes a STLT will generate and public private key pair and send them to ReportStream to authenticate. The format in which they are sent can differ from STLT to STLT. +Some STLTs will send a PFX file and that file will need to be converted to JKS so that ReportStream can use it. + +1. **Convert PFX to JKS:** + This command creates a PEM file containing both a private and public key: + ```bash + keytool -importkeystore -srckeystore mypfxfile.pfx -srcstoretype pkcs12 -destkeystore clientcert.jks -deststoretype JKS + ``` +2. **Create ReportStream Credential:** + Use the primeCLI create-credential command to store the jks file in JSON to be able to store it in Azure so that ReportStream can use it. + ```bash + ./prime credential-create --type UserJks --jks-use --jks-file-pass --jks-file + ``` + +### Importing STLTs Self-Signed Certificate to ReportStream + +As of the time this document was written, the process for importing self-signed certificates into ReportStream involves adding the certificate to ReportStream's Docker container. + +1. **Add the Certificate:** + Place the certificate in the following directory: + ``` + prime-reportstream/prime-router/certs/ + ``` + +2. **Update the Dockerfile:** + Add the certificate to the `prime-reportstream/prime-router/Dockerfile.dev` by including the following line: + ```bash + COPY ./certs/CDC-G2-S1.crt $JAVA_HOME/conf/security + RUN cd $JAVA_HOME/conf/security \ + && $JAVA_HOME/bin/keytool -cacerts -storepass changeit -noprompt -trustcacerts -importcert -alias -file + ``` + + +