Skip to main content

Non-OAuth 2.0 Authentication

  • Epic supports forms of authentication in addition to OAuth 2.0. Only use these forms of authentication if OAuth 2.0 is not an option.

HTTP Basic Authentication​

  • HTTP Basic Authentication requires that Epic community members provision a username and password that your application will provide to the web server to authenticate every request.

  • Epic supports HTTP Basic Authentication via a system-level user record created within Epic's database.

  • You may hear this referred to as an EMP record.

  • You will need to work with an organization's Epic user security team to have a username and password provided to you.

  • When calling Epic's web services with HTTP Basic Authentication the username must be provided as follows: 

emp$<username>.

  • Replace username with the username provided by the organization during implementation of your application.

  • Base64 encode your application's credentials and pass them in the HTTP Authorization header.

  • For example, if you've been given a system-level username/password combination that is username/Pa$$w0rd1, the Authorization header would have a value of ZW1wJHVzZXJuYW1lOlBhJCR3MHJkMQ== (the base64 encoded version of emp$username:Pa$$w0rd1):

GET http://localhost:8888/website HTTP/1.1
Host: localhost:8888
Proxy-Connection: keep-alive
Authorization: Basic ZW1wJHVzZXJuYW1lOlBhJCR3MHJkMQ==

Storing HTTP Basic Authentication Values​

  • The username and password you use to authenticate your web service requests are extremely sensitive since they can be used to pull PHI out of an Epic organization's system.

  • The credentials should always be encrypted and should not be stored directly within your client's code.

  • You should make sure that access to decrypt the credentials should be limited to only the users that need access to it.

  • For example, if a service account submits the web service requests, only that service account should be able to decrypt the credentials.

Client Certificates and SAML tokens​

  • Epic also supports the use of Client Certificates and SAML tokens as an authentication mechanism for server-to-server web service requests.

  • We do not prefer these methods because both require web server administrators to maintain a trusted certificate for authentication.

  • As certificates expire or servers need to be moved around, this puts an additional burden on system administrators.

Additional Required Headers​

  • When you use OAuth 2.0 authentication, Epic can automatically gather important information about the client making a web service request.

  • When you use a non-OAuth 2.0 authentication mechanism, we require that this additional information be passed in an HTTP header.

Epic-Client-ID​

  • This is the client ID you were given upon your app's creation on the Epic on FHIR site.

  • This is always required when calling Epic's web services if your app doesn't use OAuth 2.0 authentication.

GET http://localhost:8888/website HTTP/1.1
Host: localhost:8888
Proxy-Connection: keep-alive
Authorization: Basic ZW1wJHVzZXJuYW1lOlBhJCR3MHJkMQ==
Epic-Client-ID: 0000-0000-0000-0000-0000

Epic-User-ID and Epic-User-IDType​

  • This is required for auditing requests to FHIR resources.

  • The Epic-User-ID corresponds to an EMP (Epic User) account that an organization creates for your application.

  • This might be required depending on the web services you are calling. The Epic-User-IDType is almost always EXTERNAL.

GET http://localhost:8888/website HTTP/1.1
Host: localhost:8888
Proxy-Connection: keep-alive
Authorization: Basic ZW1wJHVzZXJuYW1lOlBhJCR3MHJkMQ==
Epic-Client-ID: 0000-0000-0000-0000-0000                        
Epic-User-ID: username                      
Epic-User-IDType: EXTERNAL