Struct ipworksauth::OpenID

Properties   Methods   Events   Config Settings   Errors  

The OpenID struct is used to verify the identify of a user as well as get basic profile information.

Syntax

ipworksauth::OpenID

Remarks

The OpenID struct implements an OpenID Connect (OIDC) Relying Party (RP) capable of authenticating a user and retrieving user information. OIDC is a simple identity layer on top of OAuth 2.0 and re-uses much of the functionality and concepts defined by OAuth 2.0.

To begin using the struct you will first need to register your application with the service you want to use. During this process you should obtain a client_id and client_secret. The following sections discuss the typical steps to verify the identity of a user and obtain profile information.

Get the Discovery Document

Many OpenID Providers (OPs) provide information via a Discovery Document. The discovery document defines information such as the endpoint URLs for authentication, tokens, and user information requests. Additionally, details about parameters such as supported authorization scopes are defined in this document. The document is found at a URL which can be fetched and parsed by calling the get_discovery_doc method.

The discovery document URL is typically published by an OpenID Provider (OP) and must be known before calling this method. The format of the URL is standardized and typically takes the form:

https://www.youropenidserver.com/.well-known/openid-configuration

Call get_discovery_doc before calling get_authorization to populate the struct properties with information required to complete the authorization. The retrieved information includes endpoint URLs as well as the OpenID public certificates used to verify the signature on the ID Token. After calling this method the following properties are populated:

• server_auth_url
• server_token_url
• server_user_info_url
• signer_cert_url

The above values may be stored, and later populated from the stored values, to avoid the requirement of calling get_discovery_doc on subsequent authorization requests.

The following discovery document fields are populated after get_discovery_doc returns:

• discovery_doc_details_authorization_url
• discovery_doc_details_claims_param_supported
• discovery_doc_details_issuer
• discovery_doc_details_signer_cert_url
• discovery_doc_details_registration_url
• discovery_doc_details_service_docs_url
• discovery_doc_details_supported_claims
• discovery_doc_details_supported_displays
• discovery_doc_details_supported_grant_types
• discovery_doc_details_supported_response_types
• discovery_doc_details_supported_scopes
• discovery_doc_details_token_url
• discovery_doc_details_user_info_url

To access values not automatically parsed by the struct the XPath configuration setting may be set to retrieve a specific value. Alternatively the RawJSON setting returns the entire JSON document which may be parsed separately.

NOTE: Calling get_discovery_doc is not mandatory. If server information was stored from a previous call or is otherwise known ahead of time the following properties may be set in place of calling get_discovery_doc:

• server_auth_url
• server_token_url
• server_user_info_url
• signer_cert_url or signer_cert

Examples of the above points: openid.GetDiscoveryDoc("https://accounts.google.com/.well-known/openid-configuration"); // ... or ... openid.ServerAuthURL = "https://accounts.google.com/o/oauth2/v2/auth"; openid.ServerTokenURL = "https://oauth2.googleapis.com/token"; openid.ServerUserInfoURL = "https://openidconnect.googleapis.com/v1/userinfo"; openid.SignerCertURL = "https://www.googleapis.com/oauth2/v3/certs"; // ... or ... string rawjson = openid.Config("RawJSON");

Get Authorization

Before calling get_authorization the struct may be configured for one of several flows defined by the grant_type property. These flows determine which information is returned by the authorization server and which information (if any) is returned by the Token server.

Possible values for grant_type are:

• 0 (Authorization Code - Default)
• 1 (Implicit)
• 2 (Hybrid)

When using 0 (Authorization Code Flow - Default), an authorization code is returned from the server_auth_url and the struct automatically contacts the server_token_url and exchanges the authorization code for an ID Token and access token.

When using 1 (Implicit Flow), the server_auth_url returns an ID Token and access token directly. This is only recommended for implementations that are in-browser, as this potentially exposes the tokens to the end-user and user agent itself.

When using 2 (Hybrid Flow), an authorization code and potentially one or more tokens are returned by the server_auth_url. The struct will automatically contact the server_token_url to exchange the authorization code for an ID Token and access token.

When grant_type and any other optional settings are set as desired, call get_authorization.

get_authorization performs several operations automatically depending on the value of client_profile. Please see the introduction section for the OpenID struct for a detailed overview of the typical scenarios.

After authorization is complete, user_details will be populated with the claims parsed from the ID Token. This method also returns an authorization string. The authorization string grants access to additional resources as requested via the authorization_scope property. If access to another resource was requested, then the access token returned here may be set in the Authorization property of any other struct (or passed as the value of the HTTP Authorization header).

get_user_info may be called after calling this method.

The following properties are applicable when calling this method:

• client_id (required)
• client_secret (required)
• server_auth_url (required - populated by get_discovery_doc.)
• server_token_url (required - populated by get_discovery_doc.)
• signer_cert_url (conditional - populated by get_discovery_doc. Required if signer_cert is not set.)
• signer_cert (conditional - required if signer_cert_url is not set.)
• authorization_scope
• client_profile
• grant_type
• params
• refresh_token
• return_url
• state
• timeout
• Display
• Prompt
• IdTokenHint
• LoginHint
• ResponseType

For the default Authorization Code flow, GetAuthorization could work like this: openid.ClientId = "client id"; openid.ClientSecret = "client secret"; openid.AuthorizationScope += " profile email"; // default value is 'openid' openid.State = "application state"; string authToken = openid.GetAuthorization();

Get User Info

When get_authorization returns, the user_details property is populated with information about the user as returned in the ID Token from the authorization server. An additional operation, get_user_info may optionally be called to query the server_user_info_url for information about the user.

Before calling the get_user_info method, a successful call to get_authorization must be made. The access token returned by get_authorization is used by the OpenID provider at server_user_info_url to identify the user for which claims are being retrieved.

When this method is called the struct requests the claims about the user from the server_user_info_url. The resulting claims are available in the user_details property.

Note: The get_user_info method will populate the user_details property with the claims returned in the ID Token during the authorization process. This method may not need to be called in order to access the desired claims about the user.

openid.GetUserInfo(); // ... use the user info in the remainder of your application ...

Client Profile Notes

The client_profile defines the environment in which the struct is being used, and controls how the struct behaves in order to best suit that environment. Choose the profile that is closest to the runtime environment.

The following client types are currently supported by the struct:

• Application (desktop application)
• WebServer (server side application such as a web site)
• Device (an application without browser access such as a game console)
• Mobile (phone or tablet application)
• Browser (javascript application)
• JWT (server to server authentication using a JWT bearer token such as Google service account authentication)

Application Profile

The Application profile is applicable to applications that are run directly by the user. For instance, a Windows form application would use the Application profile. To authorize your application (client) using the Application profile, use the following steps:

First, set client_profile to ocpApplication. This defines the profile the struct will use. Set the client_id, client_secret, server_auth_url, and server_token_url to the values you obtained when registering your application.

Second, call get_authorization to begin the authorization process. When get_authorization is called, the struct will build the URL to which the user will be directed and fire the on_launch_browser event. The struct will then launch the browser using the command and URL shown in the on_launch_browser event and await the response. The duration for which the struct will wait for a response is defined by BrowserResponseTimeout.

Third, the user will interact with the browser to authenticate and grant access to the connecting application. The user will then be redirected back to an embedded web server that was automatically started when get_authorization was called. At this time, the on_return_url event will fire. This event provides an opportunity to provide a custom response to your user that they will see in their browser.

Fourth, the struct will then automatically exchange the grant that was returned by the authorization server for the access token using the HTTP endpoint specified in server_token_url.

The authorization is now complete and the get_authorization method will return the authorization string. The authorization string can then be used with any of our components by simply setting the returned value to the authorization property before making a request.

The following is a simple example: component.ClientId = "CLIENT_ID"; component.ClientSecret = "CLIENT_ID"; component.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth"; component.ServerTokenURL = "https://accounts.google.com/o/oauth2/token"; HTTP.Authorization = component.GetAuthorization(); HTTP.Get("https://www.googleapis.com/oauth2/v1/userinfo");

Web Profile

The Web profile is applicable to applications that are run on the server side when the user uses the application from a web browser. To authorize your application (client) using this profile, use the following steps:

First, set client_profile to ocpWeb. This defines the profile the component will use. Set the client_id, client_secret, server_auth_url, and server_token_url to the values you obtained when registering your application. Set return_url to the page on your site that will be the endpoint the user is redirected back to after authentication.

Second, call get_authorization_url. This will return a URL to which the user should be redirected. Redirect the user to this URL.

Third, after the user authenticates and is returned to the page on your site specified by return_url, parse the "code" query string parameter from the incoming request to get the authorization code from the authorization server. Then, set authorization_code property to the parsed value.

Fourth, after authorization_code is set, call get_authorization to exchange the code specified in authorization_code for a token from the server specified by server_token_url. get_authorization will then return the authorization string. The authorization string can be used with any of our components by simply setting the returned value to the authorization property before making a request.

For additional details for less common profile types please see client_profile.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksAuth. Due to this, the OpenID struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of OpenID when you have finished using the instance.

Property List

---

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

access_token property (OpenID Struct)

The access token returned by the authorization server.

Syntax

fn access_token(&self ) -> Result<String, IPWorksAuthError> 
fn set_access_token(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_access_token_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property will be populated with the access token returned by the authorization server after a call to get_authorization. This will be the raw access token, whereas the return value from the get_authorization method will also include the required data so that it can be passed directly to the Authorization property of other components or added as the value of the authorization header in another client implementation.

Data Type

String

access_token_exp property (OpenID Struct)

The lifetime of the access token.

Syntax

fn access_token_exp(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

This setting holds the lifetime of the access token in seconds. For instance the value 3600 indicates that the token will expire in one hour from the time it was generated.

This property is read-only.

Data Type

i32

authorization_code property (OpenID Struct)

The authorization code that is exchanged for an access token.

Syntax

fn authorization_code(&self ) -> Result<String, IPWorksAuthError> 
fn set_authorization_code(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_authorization_code_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property is used with the AuthorizationCode grant_type. When client_profile is set to ocpApplication (Application flow), this property will be informational only, as the get_authorization method will automatically exchange this code for a token with the authorization server specified in server_token_url.

When client_profile is set to ocpWeb (Web flow), this property needs to be set to the authorization code returned from the authorization server. Typically, this value is parsed when the service redirects the user back to your website. See client_profile for more information.

If this property is set before calling get_authorization, the struct will not make a request to the authorization sever and instead will attempt to exchange the code with the authorization server for an access token.

Data Type

String

authorization_scope property (OpenID Struct)

The authorization scope used during authorization.

Syntax

fn authorization_scope(&self ) -> Result<String, IPWorksAuthError> 
fn set_authorization_scope(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_authorization_scope_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

"openid"

Remarks

This property specifies the authorization scopes sent in the authorization request. The value specified here must be a space separated list of scopes. For instance openid profile email.

The openid scope is always required to be present. The default value is openid.

After calling get_authorization this property will be updated with the scope sent in the response from the server and will indicate the scope that was actually granted.

Data Type

String

client_id property (OpenID Struct)

The Id of the client assigned when registering the application.

Syntax

fn client_id(&self ) -> Result<String, IPWorksAuthError> 
fn set_client_id(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_client_id_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property holds the Id of the client that was assigned when initially registering the application with the authorization server. This value must be specified before calling get_authorization or get_authorization_url.

Data Type

String

client_profile property (OpenID Struct)

The type of client that is requesting authorization.

Syntax

fn client_profile(&self ) -> Result<i32, IPWorksAuthError> 
fn set_client_profile(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // Application
1   // Web
2   // Device
3   // Mobile
4   // JWT

Default Value

0

Remarks

This defines the type of client that will be requesting authorization. Set this before calling get_authorization to inform the struct to act accordingly. Possible values are as follows:

Application Profile

The Application profile is applicable to applications that are run directly by the user. For instance, a Windows form application would use the Application profile. To authorize your application (client) using the Application profile, use the following steps:

First, set client_profile to ocpApplication. This defines the profile the struct will use. Set the client_id, client_secret, server_auth_url, and server_token_url to the values you obtained when registering your application.

Second, call get_authorization to begin the authorization process. When get_authorization is called, the struct will build the URL to which the user will be directed and fire the on_launch_browser event. The struct will then launch the browser using the command and URL shown in the on_launch_browser event and await the response. The duration for which the struct will wait for a response is defined by BrowserResponseTimeout.

Third, the user will interact with the browser to authenticate and grant access to the connecting application. The user will then be redirected back to an embedded web server that was automatically started when get_authorization was called. At this time, the on_return_url event will fire. This event provides an opportunity to provide a custom response to your user that they will see in their browser.

Fourth, the struct will then automatically exchange the grant that was returned by the authorization server for the access token using the HTTP endpoint specified in server_token_url.

The authorization is now complete and the get_authorization method will return the authorization string. The authorization string can then be used with any of our components by simply setting the returned value to the authorization property before making a request.

The following is a simple example: component.ClientId = "CLIENT_ID"; component.ClientSecret = "CLIENT_ID"; component.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth"; component.ServerTokenURL = "https://accounts.google.com/o/oauth2/token"; HTTP.Authorization = component.GetAuthorization(); HTTP.Get("https://www.googleapis.com/oauth2/v1/userinfo");

Web Profile

The Web profile is applicable to applications that are run on the server side when the user uses the application from a web browser. To authorize your application (client) using this profile, use the following steps:

First, set client_profile to ocpWeb. This defines the profile the component will use. Set the client_id, client_secret, server_auth_url, and server_token_url to the values you obtained when registering your application. Set return_url to the page on your site that will be the endpoint the user is redirected back to after authentication.

Second, call get_authorization_url. This will return a URL to which the user should be redirected. Redirect the user to this URL.

Third, after the user authenticates and is returned to the page on your site specified by return_url, parse the "code" query string parameter from the incoming request to get the authorization code from the authorization server. Then, set authorization_code property to the parsed value.

Fourth, after authorization_code is set, call get_authorization to exchange the code specified in authorization_code for a token from the server specified by server_token_url. get_authorization will then return the authorization string. The authorization string can be used with any of our components by simply setting the returned value to the authorization property before making a request.

Device Profile

The Device profile is applicable to applications that are run on devices for which a web browser cannot be used. For example, a game console would use the Device profile. To authorize your application (client) using the device client profile use the following steps:

First, set client_profile to ocpDevice. This defines the profile the struct will use. Set the client_id, client_secret, server_auth_url, and server_token_url to the values you obtained when registering your application. Do not set return_url.

Second, call get_authorization_url. The struct will automatically make a request to server_auth_url to obtain a user code for the device. The get_authorization_url method will return the URL your user must visit from another device or computer that has web browser support. The get_authorization_url method will also populate DeviceUserCode. This device user code must be provided to the user. The user will enter the code at the URL returned by get_authorization_url.

Third, at this time, call get_authorization. The struct will begin polling the server specified in server_token_url. The polling interval is specified (in seconds) by the PollingInterval setting.

Fourth, after the user has authenticated, the get_authorization method will return the authorization string. To use the authorization string with any of our components, simply pass this value to the authorization property before making the request.

Mobile Profile

The Mobile profile is applicable to applications that are run on devices for which a web browser can be used. For instance, a mobile phone or tablet would use the Mobile profile. The behavior when using this profile is very similar to the Application profile. The only difference between the Mobile and Application profiles is the way the browser is launched. When set to the Mobile profile, the on_launch_browser event will fire but the struct will not attempt to launch the browser automatically. The browser must be launched manually from code. This behavior is the only difference between the Mobile and Application profiles. Please read the steps for the Application profile for a more detailed look at the process.

JWT Bearer Token (Server-to-Server) Profile

The JWT (JSON Web Token) Bearer Token profile is available for server-to-server authentication. For instance this may be used by web applications to access a Google service. In this case, the application will access data on behalf of the service account, not the end user. End-user interaction is not required.

First, specify authorization_scope server_token_url and JWTServiceProvider.

Second, specify JWT-specific values. The use of the JWT profile also requires additional configuration settings to be specified, including a certificate with private key used to sign the JWT. Either specify the JWTJSONKey configuration setting, which will parse the necessary information automatically, or manually specify the following configuration settings:

• JWTIssuer (required)
• JWTAudience (required)
• JWTCertStoreType (required)
• JWTCertStore (required)
• JWTCertStorePassword (required)
• JWTCertSubject (required)
• JWTSubject
• JWTValidityTime
• JWTSignatureAlgorithm

Additional fields may be added to the JWT using the add_param method.

Example 1. Google: oauth.AuthorizationScope = "https://www.googleapis.com/auth/analytics"; oauth.ServerTokenURL = "https://www.googleapis.com/oauth2/v3/token"; oauth.ClientProfile = OauthClientProfiles.ocpJWT; oauth.Config("JWTServiceProvider=0"); oauth.Config("JWTIssuer=CLIENT_ID"); oauth.Config("JWTAudience=https://www.googleapis.com/oauth2/v3/token"); oauth.Config("JWTCertStoreType=2"); oauth.Config("JWTCertStore=C:\\MyCertificate.p12"); oauth.Config("JWTCertStorePassword=password"); oauth.Config("JWTCertSubject=*"); oauth.Config("JWTValidityTime=5400"); //in seconds string authStr = oauth.GetAuthorization();

Example 2. Microsoft: oauth.ClientId = "Client_Id"; oauth.ClientProfile = OauthClientProfiles.ocpJWT; oauth.AuthorizationScope = "https://graph.microsoft.com/.default"; oauth.ServerTokenURL = "https://login.microsoftonline.com/" + tenant_id + "/oauth2/V2.0/token"; oauth.Config("JWTServiceProvider=1"); oauth.Config("JWTIssuer=" + CLIENT_ID); oauth.Config("JWTSubject=" + CLIENT_ID); oauth.Config("JWTCertStoreType=2"); oauth.Config("JWTCertStore=C:\\MyCertificate.p12"); oauth.Config("JWTCertStorePassword=password"); oauth.Config("JWTCertSubject=*"); oauth.Config("JWTValidityTime=3600"); oauth.Config("JWTAudience=https://login.microsoftonline.com/"+ tenant_id + "/oauth2/V2.0/token"); string authStr = oauth.GetAuthorization();

Data Type

i32

client_secret property (OpenID Struct)

The secret value for the client assigned when registering the application.

Syntax

fn client_secret(&self ) -> Result<String, IPWorksAuthError> 
fn set_client_secret(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_client_secret_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property holds the secret of the client that was assigned when initially registering the application with the authorization server. This value must be specified before calling get_authorization or get_authorization_url.

Data Type

String

connected property (OpenID Struct)

Whether the struct is connected.

Syntax

fn connected(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

This property is used to determine whether or not the struct is connected to the remote host. Use the connect and disconnect methods to manage the connection.

This property is read-only.

Data Type

bool

cookie_count property (OpenID Struct)

The number of records in the Cookie arrays.

Syntax

fn cookie_count(&self ) -> Result<i32, IPWorksAuthError> 
fn set_cookie_count(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• cookie_domain
• cookie_expiration
• cookie_name
• cookie_path
• cookie_secure
• cookie_value

The array indices start at 0 and end at cookie_count - 1.

Data Type

i32

cookie_domain property (OpenID Struct)

The domain of a received cookie.

Syntax

fn cookie_domain(&self , CookieIndex : i32) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The domain of a received cookie. This property contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, this property will contain an empty string. The convention in this case is to use the server name specified by url_server as the cookie domain.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the CookieCount property.

This property is read-only.

Data Type

String

cookie_expiration property (OpenID Struct)

An expiration time for the cookie (if provided by the server).

Syntax

fn cookie_expiration(&self , CookieIndex : i32) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

An expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, this property will contain an empty string. The convention is to drop the cookie at the end of the session.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the CookieCount property.

This property is read-only.

Data Type

String

cookie_name property (OpenID Struct)

The name of the cookie.

Syntax

fn cookie_name(&self , CookieIndex : i32) -> Result<String, IPWorksAuthError> 
fn set_cookie_name(&self, CookieIndex : i32, value : &str) ->  Option<IPWorksAuthError> 
fn set_cookie_name_ref(&self, CookieIndex : i32, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The name of the cookie.

This property, along with cookie_value, stores the cookie that is to be sent to the server. The on_set_cookie event displays the cookies sent by the server and their properties.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the CookieCount property.

Data Type

String

cookie_path property (OpenID Struct)

A path name to limit the cookie to (if provided by the server).

Syntax

fn cookie_path(&self , CookieIndex : i32) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the path property will be an empty string. The convention in this case is to use the path specified by url_path as the cookie path.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the CookieCount property.

This property is read-only.

Data Type

String

cookie_secure property (OpenID Struct)

The security flag of the received cookie.

Syntax

fn cookie_secure(&self , CookieIndex : i32) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

The security flag of the received cookie. This property specifies whether the cookie is secure. If the value of this property is True, the cookie value must be submitted only through a secure (HTTPS) connection.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the CookieCount property.

This property is read-only.

Data Type

bool

cookie_value property (OpenID Struct)

The value of the cookie.

Syntax

fn cookie_value(&self , CookieIndex : i32) -> Result<String, IPWorksAuthError> 
fn set_cookie_value(&self, CookieIndex : i32, value : &str) ->  Option<IPWorksAuthError> 
fn set_cookie_value_ref(&self, CookieIndex : i32, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The value of the cookie. A corresponding value is associated with the cookie specified by cookie_name. This property holds that value.

The on_set_cookie event provides the cookies set by the server.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the CookieCount property.

Data Type

String

discovery_doc_details_authorization_url property (OpenID Struct)

The server authorization endpoint URL.

Syntax

fn discovery_doc_details_authorization_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The server authorization endpoint URL.

This setting corresponds to the authorization_endpoint parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_claims_param_supported property (OpenID Struct)

Whether the claims request parameter is supported by the Open ID provider.

Syntax

fn discovery_doc_details_claims_param_supported(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether the claims request parameter is supported by the Open ID provider.

This setting corresponds to the claims_parameter_supported parameter in the discovery document.

This property is read-only.

Data Type

bool

discovery_doc_details_content property (OpenID Struct)

The raw discovery document JSON.

Syntax

fn discovery_doc_details_content(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The raw discovery document JSON.

This property is read-only.

Data Type

String

discovery_doc_details_issuer property (OpenID Struct)

The issuer identifier of the OpenID provider.

Syntax

fn discovery_doc_details_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer identifier of the OpenID provider. This value is the same as the iss claim returned in ID Tokens issued from this provider. The value is a URL with the https scheme with no query string or fragment component.

This setting corresponds to the issuer parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_logout_url property (OpenID Struct)

The logout endpoint URL.

Syntax

fn discovery_doc_details_logout_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The logout endpoint URL.

This setting corresponds to the optional end_session_endpoint parameter that may be found in the discovery document. If a user is directed to this URL, they will be asked to log out of their account.

This property is read-only.

Data Type

String

discovery_doc_details_registration_url property (OpenID Struct)

The dynamic client registration URL.

Syntax

fn discovery_doc_details_registration_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The dynamic client registration URL.

This setting corresponds to the registration_endpoint parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_service_docs_url property (OpenID Struct)

The URL of the human-readable service documentation.

Syntax

fn discovery_doc_details_service_docs_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The URL of the human-readable service documentation. The information at this URL is intended for developers integrating with the OpenID provider and may contain useful information.

This setting corresponds to the service_documentation parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_signer_cert_url property (OpenID Struct)

The URL of the JSON Web Key Set used to verify signatures on values returned by the OpenID provider.

Syntax

fn discovery_doc_details_signer_cert_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The URL of the JSON Web Key Set used to verify signatures on values returned by the OpenID provider. The signer keys are automatically retrieved by the struct when the ID Token signature verification is performed.

This setting corresponds to the jwks_uri parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_supported_claims property (OpenID Struct)

A comma-separated list of claims that are supported by the OpenID provider.

Syntax

fn discovery_doc_details_supported_claims(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-separated list of claims that are supported by the OpenID provider. For instance: aud,email,email_verified,exp,family_name,given_name,iat,iss,locale,name,picture,sub

This setting corresponds to the claims_supported parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_supported_displays property (OpenID Struct)

A comma-separated list of display values that are supported by the OpenID provider.

Syntax

fn discovery_doc_details_supported_displays(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-separated list of display values that are supported by the OpenID provider.

This setting corresponds to the display_values_supported parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_supported_grant_types property (OpenID Struct)

A comma-separated list of grant types supported by the OpenID provider.

Syntax

fn discovery_doc_details_supported_grant_types(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-separated list of grant types supported by the OpenID provider. If this value is not specified by the OpenID provider, it is specified that authorization_code and implicit are supported by the OpenID provider.

This setting corresponds to the grant_types_supported parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_supported_response_types property (OpenID Struct)

A comma-separated list of response types supported by the OpenID provider.

Syntax

fn discovery_doc_details_supported_response_types(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-separated list of response types supported by the OpenID provider. If this value is not specified by the OpenID provider, it is defined that the OpenID provider supports (at a minimum) the code, id_token, and token id_token values.

This setting corresponds to the response_types_supported parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_supported_scopes property (OpenID Struct)

A comma-separated list of scopes that are supported by the OpenID provider.

Syntax

fn discovery_doc_details_supported_scopes(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-separated list of scopes that are supported by the OpenID provider. For instance: openid,email,profile

This setting corresponds to the scopes_supported parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_token_url property (OpenID Struct)

The token endpoint URL.

Syntax

fn discovery_doc_details_token_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The token endpoint URL.

This setting corresponds to the token_endpoint parameter in the discovery document.

This property is read-only.

Data Type

String

discovery_doc_details_user_info_url property (OpenID Struct)

The user info endpoint URL.

Syntax

fn discovery_doc_details_user_info_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user info endpoint URL.

This setting corresponds to the userinfo_endpoint parameter in the discovery document.

This property is read-only.

Data Type

String

firewall_auto_detect property (OpenID Struct)

Whether to automatically detect and use firewall system settings, if available.

Syntax

fn firewall_auto_detect(&self ) -> Result<bool, IPWorksAuthError> 
fn set_firewall_auto_detect(&self, value : bool) ->  Option<IPWorksAuthError> 

Default Value

false

Remarks

Whether to automatically detect and use firewall system settings, if available.

Data Type

bool

firewall_type property (OpenID Struct)

The type of firewall to connect through.

Syntax

fn firewall_type(&self ) -> Result<i32, IPWorksAuthError> 
fn set_firewall_type(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // None
1   // Tunnel
2   // SOCKS4
3   // SOCKS5
10   // SOCKS4A

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

Data Type

i32

firewall_host property (OpenID Struct)

The name or IP address of the firewall (optional).

Syntax

fn firewall_host(&self ) -> Result<String, IPWorksAuthError> 
fn set_firewall_host(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_firewall_host_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the struct fails with an error.

Data Type

String

firewall_password property (OpenID Struct)

A password if authentication is to be used when connecting through the firewall.

Syntax

fn firewall_password(&self ) -> Result<String, IPWorksAuthError> 
fn set_firewall_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_firewall_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the struct fails with an error.

Data Type

String

firewall_port property (OpenID Struct)

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

fn firewall_port(&self ) -> Result<i32, IPWorksAuthError> 
fn set_firewall_port(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

NOTE: This property is set automatically when firewall_firewall_type is set to a valid value. See the description of the firewall_firewall_type property for details.

Data Type

i32

firewall_user property (OpenID Struct)

A username if authentication is to be used when connecting through a firewall.

Syntax

fn firewall_user(&self ) -> Result<String, IPWorksAuthError> 
fn set_firewall_user(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_firewall_user_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If firewall_host is specified, this property and the firewall_password property are used to connect and authenticate to the given Firewall. If the authentication fails, the struct fails with an error.

Data Type

String

follow_redirects property (OpenID Struct)

Determines what happens when the server issues a redirect.

Syntax

fn follow_redirects(&self ) -> Result<i32, IPWorksAuthError> 
fn set_follow_redirects(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // Never
1   // Always
2   // SameScheme

Default Value

0

Remarks

This property determines what happens when the server issues a redirect. Normally, the struct returns an error if the server responds with an "Object Moved" message. If this property is set to frAlways (1), the new url for the object is retrieved automatically every time.

If this property is set to frSameScheme (2), the new url is retrieved automatically only if the url_scheme is the same; otherwise, the struct fails with an error.

NOTE: Following the HTTP specification, unless this property is set to frAlways (1), automatic redirects will be performed only for GET or HEAD requests. Other methods potentially could change the conditions of the initial request and create security vulnerabilities.

Furthermore, if either the new URL server or port are different from the existing one, user and password are also reset to empty. If, however, this property is set to frAlways (1), the same credentials are used to connect to the new server.

A on_redirect event is fired for every URL the product is redirected to. In the case of automatic redirections, the on_redirect event is a good place to set properties related to the new connection (e.g., new authentication parameters).

The default value is frNever (0). In this case, redirects are never followed, and the struct fails with an error instead.

Data Type

i32

grant_type property (OpenID Struct)

The grant type defining the authentication flow.

Syntax

fn grant_type(&self ) -> Result<i32, IPWorksAuthError> 
fn set_grant_type(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // AuthorizationCode
1   // Implicit
2   // Hybrid

Default Value

0

Remarks

This property defines the grant type used when performing authentication. The value specified here controls the authentication flow.

Possible values for grant_type are:

• 0 (Authorization Code - Default)
• 1 (Implicit)
• 2 (Hybrid)

When using 0 (Authorization Code Flow - Default), an authorization code is returned from the server_auth_url and the struct automatically contacts the server_token_url and exchanges the authorization code for an ID Token and access token.

When using 1 (Implicit Flow), the server_auth_url returns an ID Token and access token directly. This is only recommended for implementations that are in-browser, as this potentially exposes the tokens to the end-user and user agent itself.

When using 2 (Hybrid Flow), an authorization code and potentially one or more tokens are returned by the server_auth_url. The struct will automatically contact the server_token_url to exchange the authorization code for an ID Token and access token.

Additional Notes

The response_type request parameter is automatically set based on the value specified here. In some cases multiple values are acceptable and a default value is chosen automatically. To explicitly specify a response_type value for the chosen grant type set ResponseType after setting this property.

Data Type

i32

idle property (OpenID Struct)

The current status of the struct.

Syntax

fn idle(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

true

Remarks

This property will be False if the component is currently busy (communicating or waiting for an answer), and True at all other times.

This property is read-only.

Data Type

bool

id_token_audiences property (OpenID Struct)

A comma-separated list of audiences for which the ID Token is intended.

Syntax

fn id_token_audiences(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-separated list of audiences for which the ID Token is intended.

This property is read-only.

Data Type

String

id_token_auth_time property (OpenID Struct)

The time when the end user authenticates with the authorization server.

Syntax

fn id_token_auth_time(&self ) -> Result<i64, IPWorksAuthError> 

Default Value

0

Remarks

The time when the end user authenticates with the authorization server.

The time value is a number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

This property is read-only.

Data Type

i64

id_token_exp_time property (OpenID Struct)

The time when the ID Token expires.

Syntax

fn id_token_exp_time(&self ) -> Result<i64, IPWorksAuthError> 

Default Value

0

Remarks

The time when the ID Token expires.

The time value is a number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

This property is read-only.

Data Type

i64

id_token_content property (OpenID Struct)

The raw value of the ID Token.

Syntax

fn id_token_content(&self ) -> Result<String, IPWorksAuthError> 
fn set_id_token_content(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_id_token_content_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The raw value of the ID Token.

Data Type

String

id_token_issued_time property (OpenID Struct)

The time when the authentication for this ID Token occurred.

Syntax

fn id_token_issued_time(&self ) -> Result<i64, IPWorksAuthError> 

Default Value

0

Remarks

The time when the authentication for this ID Token occurred.

The time value is a number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

This property is read-only.

Data Type

i64

id_token_issuer property (OpenID Struct)

The issuer, or authorization server, that constructed the ID Token.

Syntax

fn id_token_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer, or authorization server, that constructed the ID Token.

This property is read-only.

Data Type

String

local_host property (OpenID Struct)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn local_host(&self ) -> Result<String, IPWorksAuthError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the struct initiate connections (or accept in the case of server structs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the struct is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

Data Type

String

other_headers property (OpenID Struct)

Other headers as determined by the user (optional).

Syntax

fn other_headers(&self ) -> Result<String, IPWorksAuthError> 
fn set_other_headers(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_other_headers_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property can be set to a string of headers to be appended to the HTTP request headers created from other properties like content_type and from.

The headers must follow the format Header: Value as described in the HTTP specifications. Header lines should be separated by CRLF ("\r\n") .

Use this property with caution. If this property contains invalid headers, HTTP requests may fail.

This property is useful for extending the functionality of the struct beyond what is provided.

Data Type

String

param_count property (OpenID Struct)

The number of records in the Param arrays.

Syntax

fn param_count(&self ) -> Result<i32, IPWorksAuthError> 
fn set_param_count(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• param_name
• param_value

The array indices start at 0 and end at param_count - 1.

Data Type

i32

param_name property (OpenID Struct)

The name of the parameter to be used in the request or returned in the response.

Syntax

fn param_name(&self , ParamIndex : i32) -> Result<String, IPWorksAuthError> 
fn set_param_name(&self, ParamIndex : i32, value : &str) ->  Option<IPWorksAuthError> 
fn set_param_name_ref(&self, ParamIndex : i32, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The name of the parameter to be used in the request or returned in the response.

The ParamIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ParamCount property.

Data Type

String

param_value property (OpenID Struct)

The value of the parameter to be used in the request or returned in the response.

Syntax

fn param_value(&self , ParamIndex : i32) -> Result<String, IPWorksAuthError> 
fn set_param_value(&self, ParamIndex : i32, value : &str) ->  Option<IPWorksAuthError> 
fn set_param_value_ref(&self, ParamIndex : i32, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The value of the parameter to be used in the request or returned in the response. When issuing a request, the struct will URL encode the value specified here. Returned values will be automatically URL decoded.

The ParamIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ParamCount property.

Data Type

String

proxy_auth_scheme property (OpenID Struct)

The type of authorization to perform when connecting to the proxy.

Syntax

fn proxy_auth_scheme(&self ) -> Result<i32, IPWorksAuthError> 
fn set_proxy_auth_scheme(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // Basic
1   // Digest
2   // Proprietary
3   // None
4   // Ntlm
5   // Negotiate

Default Value

0

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the proxy_user and proxy_password properties are set.

proxy_auth_scheme should be set to authNone (3) when no authentication is expected.

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the struct will attempt basic authentication.

If proxy_auth_scheme is set to authDigest (1), digest authentication will be attempted instead.

If proxy_auth_scheme is set to authProprietary (2), then the authorization token will not be generated by the struct. Look at the configuration file for the struct being used to find more information about manually setting this token.

If proxy_auth_scheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

Data Type

i32

proxy_auto_detect property (OpenID Struct)

Whether to automatically detect and use proxy system settings, if available.

Syntax

fn proxy_auto_detect(&self ) -> Result<bool, IPWorksAuthError> 
fn set_proxy_auto_detect(&self, value : bool) ->  Option<IPWorksAuthError> 

Default Value

false

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is false.

Data Type

bool

proxy_password property (OpenID Struct)

A password if authentication is to be used for the proxy.

Syntax

fn proxy_password(&self ) -> Result<String, IPWorksAuthError> 
fn set_proxy_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_proxy_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

Data Type

String

proxy_port property (OpenID Struct)

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

fn proxy_port(&self ) -> Result<i32, IPWorksAuthError> 
fn set_proxy_port(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy proxy_server (default 80). See the description of the proxy_server property for details.

Data Type

i32

proxy_server property (OpenID Struct)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

fn proxy_server(&self ) -> Result<String, IPWorksAuthError> 
fn set_proxy_server(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_proxy_server_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

If a proxy proxy_server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the proxy_server property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the proxy_server property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

proxy_ssl property (OpenID Struct)

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

fn proxy_ssl(&self ) -> Result<i32, IPWorksAuthError> 
fn set_proxy_ssl(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // Automatic
1   // Always
2   // Never
3   // Tunnel

Default Value

0

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

i32

proxy_user property (OpenID Struct)

A username if authentication is to be used for the proxy.

Syntax

fn proxy_user(&self ) -> Result<String, IPWorksAuthError> 
fn set_proxy_user(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_proxy_user_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

Data Type

String

refresh_token property (OpenID Struct)

The refresh token received from or sent to the authorization server.

Syntax

fn refresh_token(&self ) -> Result<String, IPWorksAuthError> 
fn set_refresh_token(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_refresh_token_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

When get_authorization is called, if the authorization server returns a refresh token along with the access token, this property will hold the refresh token. Save this value for later use.

When your access token expires, set this property to the corresponding refresh token. Then call get_authorization, and the struct will use this token to retrieve a new access token. The new authorization string will be returned by the get_authorization method. No user interaction is required when refreshing an access token.

Data Type

String

return_url property (OpenID Struct)

The URL where the user (browser) returns after authenticating.

Syntax

fn return_url(&self ) -> Result<String, IPWorksAuthError> 
fn set_return_url(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_return_url_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

When client_profile is set to ocpApplication, this will be automatically set to the address of the local embedded web server. In that case, this property can be inspected to determine the URL where the user will be redirected, but it does not need to be set.

When calling get_authorization_url, which is common when client_profile is set to ocpWeb, set this property to the URL on your server where the user will be redirected after authenticating with the authorization server.

This property corresponds to the redirect_uri query string parameter.

Data Type

String

server_auth_url property (OpenID Struct)

The URL of the authorization server.

Syntax

fn server_auth_url(&self ) -> Result<String, IPWorksAuthError> 
fn set_server_auth_url(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_server_auth_url_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property specifies the URL of the authorization server used when get_authorization is called. This value is used when constructing the URL to which the user will be redirected to authenticate and grant access.

This should be specified before calling get_authorization.

Data Type

String

server_token_url property (OpenID Struct)

The URL used to obtain the access token.

Syntax

fn server_token_url(&self ) -> Result<String, IPWorksAuthError> 
fn set_server_token_url(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_server_token_url_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The property specifies the URL where the grant will be exchanged for the access token. This is typically a separate HTTP endpoint on the authorization server.

This must be set before calling get_authorization.

Data Type

String

server_user_info_url property (OpenID Struct)

The URL of the OpenID provider's user info endpoint.

Syntax

fn server_user_info_url(&self ) -> Result<String, IPWorksAuthError> 
fn set_server_user_info_url(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_server_user_info_url_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property holds the URL of the OpenID provider's user info endpoint. This value is required when calling get_user_info.

This property is populated when get_discovery_doc is called.

Data Type

String

signer_cert_effective_date property (OpenID Struct)

The date on which this certificate becomes valid.

Syntax

fn signer_cert_effective_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

signer_cert_expiration_date property (OpenID Struct)

The date on which the certificate expires.

Syntax

fn signer_cert_expiration_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

signer_cert_extended_key_usage property (OpenID Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn signer_cert_extended_key_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

signer_cert_fingerprint property (OpenID Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn signer_cert_fingerprint(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

signer_cert_fingerprint_sha1 property (OpenID Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn signer_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

signer_cert_fingerprint_sha256 property (OpenID Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn signer_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

signer_cert_issuer property (OpenID Struct)

The issuer of the certificate.

Syntax

fn signer_cert_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

signer_cert_private_key property (OpenID Struct)

The private key of the certificate (if available).

Syntax

fn signer_cert_private_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The signer_cert_private_key may be available but not exportable. In this case, signer_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

signer_cert_private_key_available property (OpenID Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn signer_cert_private_key_available(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether a signer_cert_private_key is available for the selected certificate. If signer_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

signer_cert_private_key_container property (OpenID Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn signer_cert_private_key_container(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The name of the signer_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

signer_cert_public_key property (OpenID Struct)

The public key of the certificate.

Syntax

fn signer_cert_public_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

signer_cert_public_key_algorithm property (OpenID Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn signer_cert_public_key_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

signer_cert_public_key_length property (OpenID Struct)

The length of the certificate's public key (in bits).

Syntax

fn signer_cert_public_key_length(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

signer_cert_serial_number property (OpenID Struct)

The serial number of the certificate encoded as a string.

Syntax

fn signer_cert_serial_number(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

signer_cert_signature_algorithm property (OpenID Struct)

The text description of the certificate's signature algorithm.

Syntax

fn signer_cert_signature_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

signer_cert_store property (OpenID Struct)

The name of the certificate store for the client certificate.

Syntax

fn signer_cert_store(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_signer_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_signer_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The signer_cert_store_type property denotes the type of the certificate store specified by signer_cert_store. If the store is password-protected, specify the password in signer_cert_store_password.

signer_cert_store is used in conjunction with the signer_cert_subject property to specify client certificates. If signer_cert_store has a value, and signer_cert_subject or signer_cert_encoded is set, a search for a certificate is initiated. Please see the signer_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

signer_cert_store_password property (OpenID Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn signer_cert_store_password(&self ) -> Result<String, IPWorksAuthError> 
fn set_signer_cert_store_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_signer_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

signer_cert_store_type property (OpenID Struct)

The type of certificate store for this certificate.

Syntax

fn signer_cert_store_type(&self ) -> Result<i32, IPWorksAuthError> 
fn set_signer_cert_store_type(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

signer_cert_subject_alt_names property (OpenID Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn signer_cert_subject_alt_names(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

signer_cert_thumbprint_md5 property (OpenID Struct)

The MD5 hash of the certificate.

Syntax

fn signer_cert_thumbprint_md5(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

signer_cert_thumbprint_sha1 property (OpenID Struct)

The SHA-1 hash of the certificate.

Syntax

fn signer_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

signer_cert_thumbprint_sha256 property (OpenID Struct)

The SHA-256 hash of the certificate.

Syntax

fn signer_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

signer_cert_usage property (OpenID Struct)

The text description of UsageFlags .

Syntax

fn signer_cert_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of signer_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

signer_cert_usage_flags property (OpenID Struct)

The flags that show intended use for the certificate.

Syntax

fn signer_cert_usage_flags(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of signer_cert_usage_flags is a combination of the following flags:

Please see the signer_cert_usage property for a text representation of signer_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

signer_cert_version property (OpenID Struct)

The certificate's version number.

Syntax

fn signer_cert_version(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

signer_cert_subject property (OpenID Struct)

The subject of the certificate used for client authentication.

Syntax

fn signer_cert_subject(&self ) -> Result<String, IPWorksAuthError> 
fn set_signer_cert_subject(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_signer_cert_subject_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

signer_cert_encoded property (OpenID Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn signer_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_signer_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_signer_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The signer_cert_store and signer_cert_subject properties also may be used to specify a certificate.

When signer_cert_encoded is set, a search is initiated in the current signer_cert_store for the private key of the certificate. If the key is found, signer_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, signer_cert_subject is set to an empty string.

Data Type

Vec

signer_cert_url property (OpenID Struct)

The URL of the OpenID provider's signing certificate.

Syntax

fn signer_cert_url(&self ) -> Result<String, IPWorksAuthError> 
fn set_signer_cert_url(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_signer_cert_url_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property holds the URL of the OpenID provider's signing certificate. The signing certificate is used to verify the signature of the ID Token returned when calling get_authorization.

When calling get_authorization either signer_cert_url or signer_cert must be specified.

This property is populated when get_discovery_doc is called.

Data Type

String

ssl_accept_server_cert_effective_date property (OpenID Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_accept_server_cert_effective_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_accept_server_cert_expiration_date property (OpenID Struct)

The date on which the certificate expires.

Syntax

fn ssl_accept_server_cert_expiration_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_accept_server_cert_extended_key_usage property (OpenID Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_accept_server_cert_extended_key_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint property (OpenID Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint_sha1 property (OpenID Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint_sha256 property (OpenID Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_accept_server_cert_issuer property (OpenID Struct)

The issuer of the certificate.

Syntax

fn ssl_accept_server_cert_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_accept_server_cert_private_key property (OpenID Struct)

The private key of the certificate (if available).

Syntax

fn ssl_accept_server_cert_private_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_accept_server_cert_private_key may be available but not exportable. In this case, ssl_accept_server_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_accept_server_cert_private_key_available property (OpenID Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_accept_server_cert_private_key_available(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether a ssl_accept_server_cert_private_key is available for the selected certificate. If ssl_accept_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_accept_server_cert_private_key_container property (OpenID Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_accept_server_cert_private_key_container(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The name of the ssl_accept_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key property (OpenID Struct)

The public key of the certificate.

Syntax

fn ssl_accept_server_cert_public_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key_algorithm property (OpenID Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_accept_server_cert_public_key_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key_length property (OpenID Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_accept_server_cert_public_key_length(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_accept_server_cert_serial_number property (OpenID Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_accept_server_cert_serial_number(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_accept_server_cert_signature_algorithm property (OpenID Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_accept_server_cert_signature_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_accept_server_cert_store property (OpenID Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_accept_server_cert_store(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_ssl_accept_server_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_ssl_accept_server_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password-protected, specify the password in ssl_accept_server_cert_store_password.

ssl_accept_server_cert_store is used in conjunction with the ssl_accept_server_cert_subject property to specify client certificates. If ssl_accept_server_cert_store has a value, and ssl_accept_server_cert_subject or ssl_accept_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_accept_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_accept_server_cert_store_password property (OpenID Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_accept_server_cert_store_password(&self ) -> Result<String, IPWorksAuthError> 
fn set_ssl_accept_server_cert_store_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_ssl_accept_server_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_accept_server_cert_store_type property (OpenID Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_accept_server_cert_store_type(&self ) -> Result<i32, IPWorksAuthError> 
fn set_ssl_accept_server_cert_store_type(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_accept_server_cert_subject_alt_names property (OpenID Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_accept_server_cert_subject_alt_names(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_md5 property (OpenID Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_md5(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_sha1 property (OpenID Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_sha256 property (OpenID Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_usage property (OpenID Struct)

The text description of UsageFlags .

Syntax

fn ssl_accept_server_cert_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of ssl_accept_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_accept_server_cert_usage_flags property (OpenID Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_accept_server_cert_usage_flags(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_accept_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_accept_server_cert_version property (OpenID Struct)

The certificate's version number.

Syntax

fn ssl_accept_server_cert_version(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_accept_server_cert_subject property (OpenID Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_accept_server_cert_subject(&self ) -> Result<String, IPWorksAuthError> 
fn set_ssl_accept_server_cert_subject(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_ssl_accept_server_cert_subject_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_accept_server_cert_encoded property (OpenID Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_accept_server_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_ssl_accept_server_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_ssl_accept_server_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

Data Type

Vec

ssl_cert_effective_date property (OpenID Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_cert_effective_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_expiration_date property (OpenID Struct)

The date on which the certificate expires.

Syntax

fn ssl_cert_expiration_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_extended_key_usage property (OpenID Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_cert_extended_key_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_cert_fingerprint property (OpenID Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha1 property (OpenID Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha256 property (OpenID Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_cert_issuer property (OpenID Struct)

The issuer of the certificate.

Syntax

fn ssl_cert_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_cert_private_key property (OpenID Struct)

The private key of the certificate (if available).

Syntax

fn ssl_cert_private_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_cert_private_key_available property (OpenID Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_cert_private_key_available(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_cert_private_key_container property (OpenID Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_cert_private_key_container(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_cert_public_key property (OpenID Struct)

The public key of the certificate.

Syntax

fn ssl_cert_public_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_cert_public_key_algorithm property (OpenID Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_cert_public_key_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_public_key_length property (OpenID Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_cert_public_key_length(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_cert_serial_number property (OpenID Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_cert_serial_number(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_cert_signature_algorithm property (OpenID Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_cert_signature_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_store property (OpenID Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_cert_store(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_ssl_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_ssl_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_cert_store_password property (OpenID Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_cert_store_password(&self ) -> Result<String, IPWorksAuthError> 
fn set_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_cert_store_type property (OpenID Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_cert_store_type(&self ) -> Result<i32, IPWorksAuthError> 
fn set_ssl_cert_store_type(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_cert_subject_alt_names property (OpenID Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_cert_subject_alt_names(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_md5 property (OpenID Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_md5(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha1 property (OpenID Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha256 property (OpenID Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_usage property (OpenID Struct)

The text description of UsageFlags .

Syntax

fn ssl_cert_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_cert_usage_flags property (OpenID Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_cert_usage_flags(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_cert_version property (OpenID Struct)

The certificate's version number.

Syntax

fn ssl_cert_version(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_cert_subject property (OpenID Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_cert_subject(&self ) -> Result<String, IPWorksAuthError> 
fn set_ssl_cert_subject(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_ssl_cert_subject_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_cert_encoded property (OpenID Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_ssl_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_ssl_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

Data Type

Vec

ssl_provider property (OpenID Struct)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

fn ssl_provider(&self ) -> Result<i32, IPWorksAuthError> 
fn set_ssl_provider(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // Automatic
1   // Platform
2   // Internal

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the struct will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

Additional Notes

In most cases using the default value (Automatic) is recommended. The struct will select a provider depending on the current platform.

When Automatic is selected, on Windows, the struct will use the platform implementation. On Linux/macOS, the struct will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the struct will always try and use the platform implementation. If the platform TLS 1.3 implementation is not available, the internal implementation will be used.

Data Type

i32

ssl_server_cert_effective_date property (OpenID Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_server_cert_effective_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_server_cert_expiration_date property (OpenID Struct)

The date on which the certificate expires.

Syntax

fn ssl_server_cert_expiration_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_server_cert_extended_key_usage property (OpenID Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_server_cert_extended_key_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint property (OpenID Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint_sha1 property (OpenID Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint_sha256 property (OpenID Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_server_cert_issuer property (OpenID Struct)

The issuer of the certificate.

Syntax

fn ssl_server_cert_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_server_cert_private_key property (OpenID Struct)

The private key of the certificate (if available).

Syntax

fn ssl_server_cert_private_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_server_cert_private_key may be available but not exportable. In this case, ssl_server_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_server_cert_private_key_available property (OpenID Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_server_cert_private_key_available(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether a ssl_server_cert_private_key is available for the selected certificate. If ssl_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_server_cert_private_key_container property (OpenID Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_server_cert_private_key_container(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The name of the ssl_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_server_cert_public_key property (OpenID Struct)

The public key of the certificate.

Syntax

fn ssl_server_cert_public_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_server_cert_public_key_algorithm property (OpenID Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_server_cert_public_key_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_server_cert_public_key_length property (OpenID Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_server_cert_public_key_length(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_server_cert_serial_number property (OpenID Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_server_cert_serial_number(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_server_cert_signature_algorithm property (OpenID Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_server_cert_signature_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_server_cert_store property (OpenID Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_server_cert_store(&self ) -> Result<Vec<u8>, IPWorksAuthError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_server_cert_store_type property denotes the type of the certificate store specified by ssl_server_cert_store. If the store is password-protected, specify the password in ssl_server_cert_store_password.

ssl_server_cert_store is used in conjunction with the ssl_server_cert_subject property to specify client certificates. If ssl_server_cert_store has a value, and ssl_server_cert_subject or ssl_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

This property is read-only.

Data Type

Vec

ssl_server_cert_store_password property (OpenID Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_server_cert_store_password(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is read-only.

Data Type

String

ssl_server_cert_store_type property (OpenID Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_server_cert_store_type(&self ) -> Result<i32, IPWorksAuthError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

This property is read-only.

Data Type

i32

ssl_server_cert_subject_alt_names property (OpenID Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_server_cert_subject_alt_names(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_md5 property (OpenID Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_md5(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_sha1 property (OpenID Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_sha256 property (OpenID Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_usage property (OpenID Struct)

The text description of UsageFlags .

Syntax

fn ssl_server_cert_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of ssl_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_server_cert_usage_flags property (OpenID Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_server_cert_usage_flags(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_server_cert_usage property for a text representation of ssl_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_server_cert_version property (OpenID Struct)

The certificate's version number.

Syntax

fn ssl_server_cert_version(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_server_cert_subject property (OpenID Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_server_cert_subject(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

This property is read-only.

Data Type

String

ssl_server_cert_encoded property (OpenID Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_server_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksAuthError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

Data Type

Vec

state property (OpenID Struct)

The opaque value used to maintain state between the request and response.

Syntax

fn state(&self ) -> Result<String, IPWorksAuthError> 
fn set_state(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_state_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property optionally holds a string value which will be returned by the authorization server with the response.

Any value may be specified here and it will be returned exactly as it was sent. This can be used to maintain state within the application, and also may be used for security purposes (for instance to prevent Cross-Site Request Forgery). The contents of this property are treated as an opaque value.

When client_profile is set to ocpApplication the on_return_url event provides the state value returned by the authorization server.

Data Type

String

timeout property (OpenID Struct)

The timeout for the struct.

Syntax

fn timeout(&self ) -> Result<i32, IPWorksAuthError> 
fn set_timeout(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

60

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the struct will wait for the operation to complete before returning control.

The struct will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If timeout expires, and the operation is not yet complete, the struct fails with an error.

NOTE: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 60 seconds.

Data Type

i32

transferred_data property (OpenID Struct)

The contents of the last response from the server.

Syntax

fn transferred_data(&self ) -> Result<Vec<u8>, IPWorksAuthError> 

Default Value

""

Remarks

This property contains the contents of the last response from the server.

TransferredDataLimit controls the maximum amount of data accumulated in transferred_data (by default, there is no limit).

This property is read-only.

Data Type

Vec

transferred_headers property (OpenID Struct)

The full set of headers as received from the server.

Syntax

fn transferred_headers(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

This property returns the complete set of raw headers as received from the server.

The on_header event shows the individual headers as parsed by the struct.

This property is read-only.

Data Type

String

use_pkce property (OpenID Struct)

Whether Proof Key for Code Exchange (PKCE) should be used.

Syntax

fn use_pkce(&self ) -> Result<bool, IPWorksAuthError> 
fn set_use_pkce(&self, value : bool) ->  Option<IPWorksAuthError> 

Default Value

false

Remarks

If specified, Proof Key for Code Exchange (PKCE) defined by RFC 7636 will be used when get_authorization is called. This applies when using the Authorization Code grant_type. The PKCEChallengeEncoding configuration setting can be used to control the code challenge method that will be used. When using the ocpWeb client_profile, the PKCEVerifier configuration setting can be used to get/set the verifier that was used to generate the challenge. See the PKCEVerifier documentation for more information.

Data Type

bool

user_details_addr_country property (OpenID Struct)

The country name portion of the user's address.

Syntax

fn user_details_addr_country(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The country name portion of the user's address.

This property is read-only.

Data Type

String

user_details_addr_formatted property (OpenID Struct)

The full mailing address of the user, formatted for display or use on a mailing label.

Syntax

fn user_details_addr_formatted(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The full mailing address of the user, formatted for display or use on a mailing label. This value may contain multiple lines.

This property is read-only.

Data Type

String

user_details_addr_locality property (OpenID Struct)

The city or locality portion of the user's address.

Syntax

fn user_details_addr_locality(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The city or locality portion of the user's address.

This property is read-only.

Data Type

String

user_details_addr_postal_code property (OpenID Struct)

The zip code or postal code portion of the user's address.

Syntax

fn user_details_addr_postal_code(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The zip code or postal code portion of the user's address.

This property is read-only.

Data Type

String

user_details_addr_region property (OpenID Struct)

The state, province, prefecture, or region portion of the user's address.

Syntax

fn user_details_addr_region(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The state, province, prefecture, or region portion of the user's address.

This property is read-only.

Data Type

String

user_details_addr_street_addr property (OpenID Struct)

The street address portion of the user's address.

Syntax

fn user_details_addr_street_addr(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The street address portion of the user's address. This is the full street address which may include house number, street name, post office box, and multi-line extended street information. This value may contain multiple lines.

This property is read-only.

Data Type

String

user_details_birthday property (OpenID Struct)

The user's birthday.

Syntax

fn user_details_birthday(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user's birthday. The format of the value is YYYY-MM-DD or YYYY. The year may be 0000 to indicate that it was omitted.

This property is read-only.

Data Type

String

user_details_email property (OpenID Struct)

The user's preferred email address.

Syntax

fn user_details_email(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user's preferred email address.

This property is read-only.

Data Type

String

user_details_email_verified property (OpenID Struct)

Whether the user's email address has been verified.

Syntax

fn user_details_email_verified(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether the user's email address has been verified. To be considered verified, the end-user must prove the email address was under the user's control at the time of verification.

This property is read-only.

Data Type

bool

user_details_first_name property (OpenID Struct)

The first name of the user.

Syntax

fn user_details_first_name(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The first name of the user. If multiple names are present, they are space-separated.

This property is read-only.

Data Type

String

user_details_gender property (OpenID Struct)

The user's gender.

Syntax

fn user_details_gender(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user's gender. Defined values are male and female, but other values may also be used.

This property is read-only.

Data Type

String

user_details_last_name property (OpenID Struct)

The last name of the user.

Syntax

fn user_details_last_name(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The last name of the user. If multiple names are present, they are space-separated.

This property is read-only.

Data Type

String

user_details_locale property (OpenID Struct)

The end user's locale.

Syntax

fn user_details_locale(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The end user's locale. This is represented as a BCP47 (RFC 5646) language tag. For instance, en-US or en_US.

This property is read-only.

Data Type

String

user_details_middle_name property (OpenID Struct)

The middle name of the user.

Syntax

fn user_details_middle_name(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The middle name of the user. If multiple names are present, they are space-separated.

This property is read-only.

Data Type

String

user_details_name property (OpenID Struct)

The user's full name in displayable form including all name parts.

Syntax

fn user_details_name(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user's full name in displayable form including all name parts. This may include titles and suffixes.

This property is read-only.

Data Type

String

user_details_nickname property (OpenID Struct)

The casual name of the user.

Syntax

fn user_details_nickname(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The casual name of the user. This may or may not be the same as user_details_first_name.

This property is read-only.

Data Type

String

user_details_phone_number property (OpenID Struct)

The user's phone number.

Syntax

fn user_details_phone_number(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user's phone number. This may be in E.164 format, for instance +1 (425) 555-1212. If an extension is present, it may be represented according to RFC 3966. For instance: +1 (604) 555-1234;ext=5678.

This property is read-only.

Data Type

String

user_details_phone_number_verified property (OpenID Struct)

Whether the user's phone number has been verified.

Syntax

fn user_details_phone_number_verified(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether the user's phone number has been verified. To be considered verified, the end-user must prove the phone number was under the user's control at the time of verification.

This property is read-only.

Data Type

bool

user_details_picture_url property (OpenID Struct)

The URL of the user's profile picture.

Syntax

fn user_details_picture_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The URL of the user's profile picture.

This property is read-only.

Data Type

String

user_details_preferred_username property (OpenID Struct)

The shorthand name by which the end-user wishes to be referred.

Syntax

fn user_details_preferred_username(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The shorthand name by which the end-user wishes to be referred.

This property is read-only.

Data Type

String

user_details_profile_url property (OpenID Struct)

The URL of the user's profile page.

Syntax

fn user_details_profile_url(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The URL of the user's profile page.

This property is read-only.

Data Type

String

user_details_subject property (OpenID Struct)

The subject of the user that is being represented.

Syntax

fn user_details_subject(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The subject of the user that is being represented. This property is set when parsed from an ID Token or after retrieving the user info. Typically this represents the user of the application.

This property is read-only.

Data Type

String

user_details_updated_at property (OpenID Struct)

The time when the user's information was last updated.

Syntax

fn user_details_updated_at(&self ) -> Result<i64, IPWorksAuthError> 

Default Value

0

Remarks

The time when the user's information was last updated.

The time value is a number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

This property is read-only.

Data Type

i64

user_details_website property (OpenID Struct)

The URL of the user's website.

Syntax

fn user_details_website(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The URL of the user's website.

This property is read-only.

Data Type

String

user_details_zone_info property (OpenID Struct)

The user's time zone.

Syntax

fn user_details_zone_info(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The user's time zone. For instance: America/Los_Angeles.

This property is read-only.

Data Type

String

web_server_port property (OpenID Struct)

The local port on which the embedded web server listens.

Syntax

fn web_server_port(&self ) -> Result<i32, IPWorksAuthError> 
fn set_web_server_port(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

0

Remarks

This property specifies the port on which the embedded web server listens. Setting this to 0 (default) enables the system to choose a port at random. The chosen port will be returned when this setting is queried after the server has started listening. This is applicable only when using the embedded web server.

Data Type

i32

web_server_ssl_cert_effective_date property (OpenID Struct)

The date on which this certificate becomes valid.

Syntax

fn web_server_ssl_cert_effective_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

web_server_ssl_cert_expiration_date property (OpenID Struct)

The date on which the certificate expires.

Syntax

fn web_server_ssl_cert_expiration_date(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

web_server_ssl_cert_extended_key_usage property (OpenID Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn web_server_ssl_cert_extended_key_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

web_server_ssl_cert_fingerprint property (OpenID Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn web_server_ssl_cert_fingerprint(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

web_server_ssl_cert_fingerprint_sha1 property (OpenID Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn web_server_ssl_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

web_server_ssl_cert_fingerprint_sha256 property (OpenID Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn web_server_ssl_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

web_server_ssl_cert_issuer property (OpenID Struct)

The issuer of the certificate.

Syntax

fn web_server_ssl_cert_issuer(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

web_server_ssl_cert_private_key property (OpenID Struct)

The private key of the certificate (if available).

Syntax

fn web_server_ssl_cert_private_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The web_server_ssl_cert_private_key may be available but not exportable. In this case, web_server_ssl_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

web_server_ssl_cert_private_key_available property (OpenID Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn web_server_ssl_cert_private_key_available(&self ) -> Result<bool, IPWorksAuthError> 

Default Value

false

Remarks

Whether a web_server_ssl_cert_private_key is available for the selected certificate. If web_server_ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

web_server_ssl_cert_private_key_container property (OpenID Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn web_server_ssl_cert_private_key_container(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The name of the web_server_ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

web_server_ssl_cert_public_key property (OpenID Struct)

The public key of the certificate.

Syntax

fn web_server_ssl_cert_public_key(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

web_server_ssl_cert_public_key_algorithm property (OpenID Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn web_server_ssl_cert_public_key_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

web_server_ssl_cert_public_key_length property (OpenID Struct)

The length of the certificate's public key (in bits).

Syntax

fn web_server_ssl_cert_public_key_length(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

web_server_ssl_cert_serial_number property (OpenID Struct)

The serial number of the certificate encoded as a string.

Syntax

fn web_server_ssl_cert_serial_number(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

web_server_ssl_cert_signature_algorithm property (OpenID Struct)

The text description of the certificate's signature algorithm.

Syntax

fn web_server_ssl_cert_signature_algorithm(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

web_server_ssl_cert_store property (OpenID Struct)

The name of the certificate store for the client certificate.

Syntax

fn web_server_ssl_cert_store(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_web_server_ssl_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_web_server_ssl_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The web_server_ssl_cert_store_type property denotes the type of the certificate store specified by web_server_ssl_cert_store. If the store is password-protected, specify the password in web_server_ssl_cert_store_password.

web_server_ssl_cert_store is used in conjunction with the web_server_ssl_cert_subject property to specify client certificates. If web_server_ssl_cert_store has a value, and web_server_ssl_cert_subject or web_server_ssl_cert_encoded is set, a search for a certificate is initiated. Please see the web_server_ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

web_server_ssl_cert_store_password property (OpenID Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn web_server_ssl_cert_store_password(&self ) -> Result<String, IPWorksAuthError> 
fn set_web_server_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_web_server_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

web_server_ssl_cert_store_type property (OpenID Struct)

The type of certificate store for this certificate.

Syntax

fn web_server_ssl_cert_store_type(&self ) -> Result<i32, IPWorksAuthError> 
fn set_web_server_ssl_cert_store_type(&self, value : i32) ->  Option<IPWorksAuthError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

web_server_ssl_cert_subject_alt_names property (OpenID Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn web_server_ssl_cert_subject_alt_names(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

web_server_ssl_cert_thumbprint_md5 property (OpenID Struct)

The MD5 hash of the certificate.

Syntax

fn web_server_ssl_cert_thumbprint_md5(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

web_server_ssl_cert_thumbprint_sha1 property (OpenID Struct)

The SHA-1 hash of the certificate.

Syntax

fn web_server_ssl_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

web_server_ssl_cert_thumbprint_sha256 property (OpenID Struct)

The SHA-256 hash of the certificate.

Syntax

fn web_server_ssl_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

web_server_ssl_cert_usage property (OpenID Struct)

The text description of UsageFlags .

Syntax

fn web_server_ssl_cert_usage(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The text description of web_server_ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

web_server_ssl_cert_usage_flags property (OpenID Struct)

The flags that show intended use for the certificate.

Syntax

fn web_server_ssl_cert_usage_flags(&self ) -> Result<i32, IPWorksAuthError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of web_server_ssl_cert_usage_flags is a combination of the following flags:

Please see the web_server_ssl_cert_usage property for a text representation of web_server_ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

web_server_ssl_cert_version property (OpenID Struct)

The certificate's version number.

Syntax

fn web_server_ssl_cert_version(&self ) -> Result<String, IPWorksAuthError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

web_server_ssl_cert_subject property (OpenID Struct)

The subject of the certificate used for client authentication.

Syntax

fn web_server_ssl_cert_subject(&self ) -> Result<String, IPWorksAuthError> 
fn set_web_server_ssl_cert_subject(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_web_server_ssl_cert_subject_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

web_server_ssl_cert_encoded property (OpenID Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn web_server_ssl_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksAuthError> 
fn set_web_server_ssl_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksAuthError> 
fn set_web_server_ssl_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The web_server_ssl_cert_store and web_server_ssl_cert_subject properties also may be used to specify a certificate.

When web_server_ssl_cert_encoded is set, a search is initiated in the current web_server_ssl_cert_store for the private key of the certificate. If the key is found, web_server_ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, web_server_ssl_cert_subject is set to an empty string.

Data Type

Vec

web_server_ssl_enabled property (OpenID Struct)

Whether the web server requires Secure Sockets Layer (SSL) connections.

Syntax

fn web_server_ssl_enabled(&self ) -> Result<bool, IPWorksAuthError> 
fn set_web_server_ssl_enabled(&self, value : bool) ->  Option<IPWorksAuthError> 

Default Value

false

Remarks

This setting specifies whether the embedded web server uses a Secure Sockets Layer (SSL). If set to True, web_server_ssl_cert is required and the server will accept only SSL connections. If set to False, only plaintext connects are supported.

Data Type

bool

add_cookie method (OpenID Struct)

Adds a cookie and the corresponding value to the outgoing request headers.

Syntax

fn add_cookie(&self, cookie_name : &str, cookie_value : &str) -> Result<(), IPWorksAuthError>

Remarks

This method adds a cookie and the corresponding value to the outgoing request headers. Please refer to the cookies property for more information on cookies and how they are managed.

add_param method (OpenID Struct)

Adds a name-value pair to the query string parameters of the outgoing request.

Syntax

fn add_param(&self, param_name : &str, param_value : &str) -> Result<(), IPWorksAuthError>

Remarks

This method can be used to add query string parameters to the outgoing request. One common use for this method would be to add the state parameter to the request, which can be used when the client_profile is ocpWeb to add user-defined data. The authorization server will include the state parameter in the response and will be available in the post back to your server, which will allow you to maintain state in your application.

config method (OpenID Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksAuthError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

do_events method (OpenID Struct)

This method processes events from the internal message queue.

Syntax

fn do_events(&self) -> Result<(), IPWorksAuthError>

Remarks

When do_events is called, the struct processes any available events. If no events are available, it waits for a preset period of time, and then returns.

get_authorization method (OpenID Struct)

Gets the authorization string required to access the protected resource.

Syntax

fn get_authorization(&self) ->  Result<String, IPWorksAuthError>

Remarks

get_authorization performs several operations automatically depending on the value of client_profile. Please see the introduction section for the OpenID struct for a detailed overview of the typical scenarios.

After authorization is complete, user_details will be populated with the claims parsed from the ID Token. This method also returns an authorization string. The authorization string grants access to additional resources as requested via the authorization_scope property. If access to another resource was requested, then the access token returned here may be set in the Authorization property of any other struct (or passed as the value of the HTTP Authorization header).

get_user_info may be called after calling this method.

The following properties are applicable when calling this method:

• client_id (required)
• client_secret (required)
• server_auth_url (required - populated by get_discovery_doc.)
• server_token_url (required - populated by get_discovery_doc.)
• signer_cert_url (conditional - populated by get_discovery_doc. Required if signer_cert is not set.)
• signer_cert (conditional - required if signer_cert_url is not set.)
• authorization_scope
• client_profile
• grant_type
• params
• refresh_token
• return_url
• state
• timeout
• Display
• Prompt
• IdTokenHint
• LoginHint
• ResponseType

get_authorization_url method (OpenID Struct)

Builds and returns the URL to which the user should be redirected for authorization.

Syntax

fn get_authorization_url(&self) ->  Result<String, IPWorksAuthError>

Remarks

When this method is called, the struct will return the URL used for authorization. The struct will not make any connections, but instead it will return the URL to you so that you may redirect the user to this location. This is useful when client_profile is set to ocpWeb. Before calling this method, set the following:

• client_id
• client_secret
• return_url
• authorization_scope (optional)

get_discovery_doc method (OpenID Struct)

Gets the OpenID Discovery Document.

Syntax

fn get_discovery_doc(&self, url : &str) -> Result<(), IPWorksAuthError>

Remarks

This method gets the OpenID Connect Discovery Document specified by the URL parameter and parses the response. The discover document contains details about the OpenID Provider configuration including endpoint URLs, supported claims and response types, and more.

The discovery document URL is typically published by an OpenID Provider (OP) and must be known before calling this method. The format of the URL is standardized and typically takes the form:

https://www.youropenidserver.com/.well-known/openid-configuration

Call get_discovery_doc before calling get_authorization to populate the struct properties with information required to complete the authorization. The retrieved information includes endpoint URLs as well as the OpenID public certificates used to verify the signature on the ID Token. After calling this method the following properties are populated:

• server_auth_url
• server_token_url
• server_user_info_url
• signer_cert_url

The above values may be stored, and later populated from the stored values, to avoid the requirement of calling get_discovery_doc on subsequent authorization requests.

The following discovery document fields are populated after get_discovery_doc returns:

• discovery_doc_details_authorization_url
• discovery_doc_details_claims_param_supported
• discovery_doc_details_issuer
• discovery_doc_details_signer_cert_url
• discovery_doc_details_registration_url
• discovery_doc_details_service_docs_url
• discovery_doc_details_supported_claims
• discovery_doc_details_supported_displays
• discovery_doc_details_supported_grant_types
• discovery_doc_details_supported_response_types
• discovery_doc_details_supported_scopes
• discovery_doc_details_token_url
• discovery_doc_details_user_info_url

To access values not automatically parsed by the struct the XPath configuration setting may be set to retrieve a specific value. Alternatively the RawJSON setting returns the entire JSON document which may be parsed separately.

get_param method (OpenID Struct)

Gets a specific parameter from a query string.

Syntax

fn get_param(&self, param_name : &str) ->  Result<String, IPWorksAuthError>

Remarks

This method can be used to get a specific parameter from a query string.

For example, when using the ocpApplication profile, this method can be used in the on_return_url event to query the parameters that are returned from the authorization server. Then, it can be called after get_authorization completes to query the parameters that the token server responded with.

string authorizationString = oauth.GetAuthorization(); string stateValue = oauth.GetParam("state");

get_user_info method (OpenID Struct)

Retrieves claims about the user.

Syntax

fn get_user_info(&self) -> Result<(), IPWorksAuthError>

Remarks

This method retrieves claims about the user. Before calling the get_user_info method, a successful call to get_authorization must be made. The access token returned by get_authorization is used by the OpenID provider at server_user_info_url to identify the user for which claims are being retrieved.

When this method is called the struct requests the claims about the user from the server_user_info_url. The resulting claims are available in the user_details property.

Note: The get_user_info method will populate the user_details property with the claims returned in the ID Token during the authorization process. This method may not need to be called in order to access the desired claims about the user.

openid.GetUserInfo(); // ... use the user info in the remainder of your application ...

interrupt method (OpenID Struct)

This method interrupts the current method.

Syntax

fn interrupt(&self) -> Result<(), IPWorksAuthError>

Remarks

If there is no method in progress, interrupt simply returns, doing nothing.

reset method (OpenID Struct)

This method will reset the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksAuthError>

Remarks

This method will reset the struct's properties to their default values.

start_web_server method (OpenID Struct)

Starts the embedded web server.

Syntax

fn start_web_server(&self) -> Result<(), IPWorksAuthError>

Remarks

This method starts the embedded web server. This method can be used to manually start the embedded web server. Under normal circumstances, this is not needed as the component will automatically start and stop the web server when get_authorization is called. You may decide, however, to start the web server manually before calling get_authorization. When called, this method will also populate return_url with the address of the embedded server.

stop_web_server method (OpenID Struct)

Stops the embedded web server.

Syntax

fn stop_web_server(&self) -> Result<(), IPWorksAuthError>

Remarks

This method stops the embedded web server. Under normal circumstances, the web server will be stopped automatically during the authorization process when get_authorization is called.

on_connected event (OpenID Struct)

Fired immediately after a connection completes (or fails).

Syntax

// OpenIDConnectedEventArgs carries the OpenID Connected event's parameters.
pub struct OpenIDConnectedEventArgs {
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// OpenIDConnectedEvent defines the signature of the OpenID Connected event's handler function.
pub trait OpenIDConnectedEvent {
  fn on_connected(&self, sender : OpenID, e : &mut OpenIDConnectedEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_connected(&self) -> &'a dyn OpenIDConnectedEvent;
  pub fn set_on_connected(&mut self, value : &'a dyn OpenIDConnectedEvent);
  ...
}

Remarks

If the connection is made normally, status_code is 0 and description is "OK".

If the connection fails, status_code has the error code returned by the Transmission Control Protocol (TCP)/IP stack. description contains a description of this code. The value of status_code is equal to the value of the error.

Please refer to the Error Codes section for more information.

on_connection_status event (OpenID Struct)

Fired to indicate changes in the connection state.

Syntax

// OpenIDConnectionStatusEventArgs carries the OpenID ConnectionStatus event's parameters.
pub struct OpenIDConnectionStatusEventArgs {
  fn connection_event(&self) -> &String
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// OpenIDConnectionStatusEvent defines the signature of the OpenID ConnectionStatus event's handler function.
pub trait OpenIDConnectionStatusEvent {
  fn on_connection_status(&self, sender : OpenID, e : &mut OpenIDConnectionStatusEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_connection_status(&self) -> &'a dyn OpenIDConnectionStatusEvent;
  pub fn set_on_connection_status(&mut self, value : &'a dyn OpenIDConnectionStatusEvent);
  ...
}

Remarks

This event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The connection_event parameter indicates the type of connection event. Values may include the following:

status_code has the error code returned by the Transmission Control Protocol (TCP)/IP stack. description contains a description of this code. The value of status_code is equal to the value of the error.

on_disconnected event (OpenID Struct)

Fired when a connection is closed.

Syntax

// OpenIDDisconnectedEventArgs carries the OpenID Disconnected event's parameters.
pub struct OpenIDDisconnectedEventArgs {
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// OpenIDDisconnectedEvent defines the signature of the OpenID Disconnected event's handler function.
pub trait OpenIDDisconnectedEvent {
  fn on_disconnected(&self, sender : OpenID, e : &mut OpenIDDisconnectedEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_disconnected(&self) -> &'a dyn OpenIDDisconnectedEvent;
  pub fn set_on_disconnected(&mut self, value : &'a dyn OpenIDDisconnectedEvent);
  ...
}

Remarks

If the connection is broken normally, status_code is 0 and description is "OK".

If the connection is broken for any other reason, status_code has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. description contains a description of this code. The value of status_code is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

on_end_transfer event (OpenID Struct)

Fired when a document finishes transferring.

Syntax

// OpenIDEndTransferEventArgs carries the OpenID EndTransfer event's parameters.
pub struct OpenIDEndTransferEventArgs {
  fn direction(&self) -> i32
}

// OpenIDEndTransferEvent defines the signature of the OpenID EndTransfer event's handler function.
pub trait OpenIDEndTransferEvent {
  fn on_end_transfer(&self, sender : OpenID, e : &mut OpenIDEndTransferEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_end_transfer(&self) -> &'a dyn OpenIDEndTransferEvent;
  pub fn set_on_end_transfer(&mut self, value : &'a dyn OpenIDEndTransferEvent);
  ...
}

Remarks

This event is fired first when the client finishes sending data to the server (in a POST or PUT request) and then when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_error event (OpenID Struct)

Fired when information is available about errors during data delivery.

Syntax

// OpenIDErrorEventArgs carries the OpenID Error event's parameters.
pub struct OpenIDErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// OpenIDErrorEvent defines the signature of the OpenID Error event's handler function.
pub trait OpenIDErrorEvent {
  fn on_error(&self, sender : OpenID, e : &mut OpenIDErrorEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_error(&self) -> &'a dyn OpenIDErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn OpenIDErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_header event (OpenID Struct)

Fired every time a header line comes in.

Syntax

// OpenIDHeaderEventArgs carries the OpenID Header event's parameters.
pub struct OpenIDHeaderEventArgs {
  fn field(&self) -> &String
  fn value(&self) -> &String
}

// OpenIDHeaderEvent defines the signature of the OpenID Header event's handler function.
pub trait OpenIDHeaderEvent {
  fn on_header(&self, sender : OpenID, e : &mut OpenIDHeaderEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_header(&self) -> &'a dyn OpenIDHeaderEvent;
  pub fn set_on_header(&mut self, value : &'a dyn OpenIDHeaderEvent);
  ...
}

Remarks

The field parameter contains the name of the HTTP header (which is the same as it is delivered). The value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the field parameter contains "" (empty string).

on_launch_browser event (OpenID Struct)

Fires before launching a browser with the authorization URL.

Syntax

// OpenIDLaunchBrowserEventArgs carries the OpenID LaunchBrowser event's parameters.
pub struct OpenIDLaunchBrowserEventArgs {
  fn url(&self) -> &String
  fn set_url(&self, value : &str)
  fn set_url_ref(&self, value : &String)
  fn command(&self) -> &String
  fn set_command(&self, value : &str)
  fn set_command_ref(&self, value : &String)
}

// OpenIDLaunchBrowserEvent defines the signature of the OpenID LaunchBrowser event's handler function.
pub trait OpenIDLaunchBrowserEvent {
  fn on_launch_browser(&self, sender : OpenID, e : &mut OpenIDLaunchBrowserEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_launch_browser(&self) -> &'a dyn OpenIDLaunchBrowserEvent;
  pub fn set_on_launch_browser(&mut self, value : &'a dyn OpenIDLaunchBrowserEvent);
  ...
}

Remarks

When the client_profile property is set to ocpApplication and get_authorization is called, the struct will fire this event with the command, which will be executed by the struct. The url parameter will be the authorization URL that the user will be directed to authenticate.

Within this event, you may override the current value of either command or url and provide your own value. If command is set to an empty string, the struct will not attempt to launch the browser and instead you will be responsible for directing the user to the authorization URL specified by the URL parameter. If command is not empty, the URL will be appended to the end.

In Windows, ShellExecute is used to execute command, which limits the verbs available for use in command to:

• edit
• explore
• find
• open
• print

on_log event (OpenID Struct)

Fired once for each log message.

Syntax

// OpenIDLogEventArgs carries the OpenID Log event's parameters.
pub struct OpenIDLogEventArgs {
  fn log_level(&self) -> i32
  fn message(&self) -> &String
  fn log_type(&self) -> &String
}

// OpenIDLogEvent defines the signature of the OpenID Log event's handler function.
pub trait OpenIDLogEvent {
  fn on_log(&self, sender : OpenID, e : &mut OpenIDLogEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_log(&self) -> &'a dyn OpenIDLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn OpenIDLogEvent);
  ...
}

Remarks

This event is fired once for each log message generated by the struct. The verbosity is controlled by the LogLevel setting.

log_level indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

message is the log entry.

log_type identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

on_redirect event (OpenID Struct)

Fired when a redirection is received from the server.

Syntax

// OpenIDRedirectEventArgs carries the OpenID Redirect event's parameters.
pub struct OpenIDRedirectEventArgs {
  fn location(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// OpenIDRedirectEvent defines the signature of the OpenID Redirect event's handler function.
pub trait OpenIDRedirectEvent {
  fn on_redirect(&self, sender : OpenID, e : &mut OpenIDRedirectEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_redirect(&self) -> &'a dyn OpenIDRedirectEvent;
  pub fn set_on_redirect(&mut self, value : &'a dyn OpenIDRedirectEvent);
  ...
}

Remarks

This event is fired in cases in which the client can decide whether or not to continue with the redirection process. The accept parameter is always True by default, but if you do not want to follow the redirection, accept may be set to False, in which case the struct fails with an error. location is the location to which the client is being redirected. Further control over redirection is provided in the follow_redirects property.

on_return_url event (OpenID Struct)

Fired when the user is redirected to the embedded web server.

Syntax

// OpenIDReturnURLEventArgs carries the OpenID ReturnURL event's parameters.
pub struct OpenIDReturnURLEventArgs {
  fn url_path(&self) -> &String
  fn query_string(&self) -> &String
  fn state(&self) -> &String
  fn response_headers(&self) -> &String
  fn set_response_headers(&self, value : &str)
  fn set_response_headers_ref(&self, value : &String)
  fn response_body(&self) -> &String
  fn set_response_body(&self, value : &str)
  fn set_response_body_ref(&self, value : &String)
}

// OpenIDReturnURLEvent defines the signature of the OpenID ReturnURL event's handler function.
pub trait OpenIDReturnURLEvent {
  fn on_return_url(&self, sender : OpenID, e : &mut OpenIDReturnURLEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_return_url(&self) -> &'a dyn OpenIDReturnURLEvent;
  pub fn set_on_return_url(&mut self, value : &'a dyn OpenIDReturnURLEvent);
  ...
}

Remarks

When client_profile is set to ocpApplication and the embedded web server is used (default), this event will fire when the user is redirected from authorization server back to the local embedded web server. The event provides an opportunity to set the ResponseHeaders and ResponseBody and provide a custom response that the user will see in their browser.

URLPath and QueryString are informational parameters that show the values sent by the authorization server.

State holds the value of the state parameter that was originally sent with the authorization request. This may be used to maintain state between the request and response. See state for more details.

on_set_cookie event (OpenID Struct)

Fired for every cookie set by the server.

Syntax

// OpenIDSetCookieEventArgs carries the OpenID SetCookie event's parameters.
pub struct OpenIDSetCookieEventArgs {
  fn name(&self) -> &String
  fn value(&self) -> &String
  fn expires(&self) -> &String
  fn domain(&self) -> &String
  fn path(&self) -> &String
  fn secure(&self) -> bool
}

// OpenIDSetCookieEvent defines the signature of the OpenID SetCookie event's handler function.
pub trait OpenIDSetCookieEvent {
  fn on_set_cookie(&self, sender : OpenID, e : &mut OpenIDSetCookieEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_set_cookie(&self) -> &'a dyn OpenIDSetCookieEvent;
  pub fn set_on_set_cookie(&mut self, value : &'a dyn OpenIDSetCookieEvent);
  ...
}

Remarks

This event is fired for every Set-Cookie: header received from the HTTP server.

The name parameter contains the name of the cookie, with the corresponding value supplied in the value parameter.

The expires parameter contains an expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, the expires parameter will be an empty string. In this case, the convention is to drop the cookie at the end of the session.

The domain parameter contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, the domain parameter will be an empty string. The convention in this case is to use the server specified in the URL (url_server) as the cookie domain.

The path parameter contains a path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the path parameter will be an empty string. The convention in this case is to use the path specified in the URL (url_path) as the cookie path.

The secure parameter specifies whether the cookie is secure. If the value of this parameter is True, the cookie value must be submitted only through a secure (HTTPS) connection.

on_ssl_server_authentication event (OpenID Struct)

Fired after the server presents its certificate to the client.

Syntax

// OpenIDSSLServerAuthenticationEventArgs carries the OpenID SSLServerAuthentication event's parameters.
pub struct OpenIDSSLServerAuthenticationEventArgs {
  fn cert_encoded(&self) -> &[u8]
  fn cert_subject(&self) -> &String
  fn cert_issuer(&self) -> &String
  fn status(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// OpenIDSSLServerAuthenticationEvent defines the signature of the OpenID SSLServerAuthentication event's handler function.
pub trait OpenIDSSLServerAuthenticationEvent {
  fn on_ssl_server_authentication(&self, sender : OpenID, e : &mut OpenIDSSLServerAuthenticationEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_ssl_server_authentication(&self) -> &'a dyn OpenIDSSLServerAuthenticationEvent;
  pub fn set_on_ssl_server_authentication(&mut self, value : &'a dyn OpenIDSSLServerAuthenticationEvent);
  ...
}

Remarks

During this event, the client can decide whether or not to continue with the connection process. The accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When accept is False, status shows why the verification failed (otherwise, status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the accept parameter to True.

on_ssl_status event (OpenID Struct)

Fired when secure connection progress messages are available.

Syntax

// OpenIDSSLStatusEventArgs carries the OpenID SSLStatus event's parameters.
pub struct OpenIDSSLStatusEventArgs {
  fn message(&self) -> &String
}

// OpenIDSSLStatusEvent defines the signature of the OpenID SSLStatus event's handler function.
pub trait OpenIDSSLStatusEvent {
  fn on_ssl_status(&self, sender : OpenID, e : &mut OpenIDSSLStatusEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_ssl_status(&self) -> &'a dyn OpenIDSSLStatusEvent;
  pub fn set_on_ssl_status(&mut self, value : &'a dyn OpenIDSSLStatusEvent);
  ...
}

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

on_start_transfer event (OpenID Struct)

Fired when a document starts transferring (after the headers).

Syntax

// OpenIDStartTransferEventArgs carries the OpenID StartTransfer event's parameters.
pub struct OpenIDStartTransferEventArgs {
  fn direction(&self) -> i32
}

// OpenIDStartTransferEvent defines the signature of the OpenID StartTransfer event's handler function.
pub trait OpenIDStartTransferEvent {
  fn on_start_transfer(&self, sender : OpenID, e : &mut OpenIDStartTransferEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_start_transfer(&self) -> &'a dyn OpenIDStartTransferEvent;
  pub fn set_on_start_transfer(&mut self, value : &'a dyn OpenIDStartTransferEvent);
  ...
}

Remarks

This event is fired first when the client starts sending data to the server (in a POST or PUT request) and then when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_status event (OpenID Struct)

Fired when the HTTP status line is received from the server.

Syntax

// OpenIDStatusEventArgs carries the OpenID Status event's parameters.
pub struct OpenIDStatusEventArgs {
  fn http_version(&self) -> &String
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// OpenIDStatusEvent defines the signature of the OpenID Status event's handler function.
pub trait OpenIDStatusEvent {
  fn on_status(&self, sender : OpenID, e : &mut OpenIDStatusEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_status(&self) -> &'a dyn OpenIDStatusEvent;
  pub fn set_on_status(&mut self, value : &'a dyn OpenIDStatusEvent);
  ...
}

Remarks

http_version is a string containing the HTTP version string as returned from the server (e.g., "1.1").

status_code contains the HTTP status code (e.g., 200), and description the associated message returned by the server (e.g., "OK").

on_transfer event (OpenID Struct)

Fired while a document transfers (delivers document).

Syntax

// OpenIDTransferEventArgs carries the OpenID Transfer event's parameters.
pub struct OpenIDTransferEventArgs {
  fn direction(&self) -> i32
  fn bytes_transferred(&self) -> i64
  fn percent_done(&self) -> i32
  fn text(&self) -> &[u8]
}

// OpenIDTransferEvent defines the signature of the OpenID Transfer event's handler function.
pub trait OpenIDTransferEvent {
  fn on_transfer(&self, sender : OpenID, e : &mut OpenIDTransferEventArgs);
}

impl <'a> OpenID<'a> {
  pub fn on_transfer(&self) -> &'a dyn OpenIDTransferEvent;
  pub fn set_on_transfer(&mut self, value : &'a dyn OpenIDTransferEvent);
  ...
}

Remarks

The text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The bytes_transferred parameter contains the number of bytes transferred in this direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

NOTE: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Config Settings (OpenID Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

OpenID Config Settings

OAuth Config Settings

WebServer Config Settings

HTTP Config Settings

TCPClient Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (OpenID Struct)

OpenID Errors

The class may also return one of the following error codes, which are inherited from other classes.

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

TCP/IP Errors