Share via

FIM CM Provision API Fundamentals

  • Article

This topic explains the fundamental concepts necessary to understand the components used by the Forefront Identity Manager Certificate Management (FIM CM) Provision API. These components include:

  • Profile templates

  • Profiles

  • Requests, request states, and request workflows

  • Permissions

  • Remoting and in-proc usage model

Profile Templates

A profile template contains a grouping of management policies. Some of the management policies are only associated with software-based certificates while others are only associated with smartcard-based certificates. Other management policies are common to both software-based and smart card-based profile templates.

The Provision API provides access to profile templates in programmatic form as READ only. Therefore, you cannot modify the profile template definitions through this API. Instances of the profile template objects are returned from a number of methods and cannot be instantiated.

For more information, see Working with Profile Templates.

Profiles

A profile is an instance of a profile template. That is, having a profile means that certificates were issued. Profiles can be either "Software" or "Smart card" type. A software profile is a container for software certificates only. A smart card profile contains certificates that are stored on a smart card. In this way, the smart card is the container for the certificates.

A profile template defines which certification authority (CA) will issue certificates for that profile and which certificate templates are included in the profile template.

When a user enters the FIM CM Subscriber Web portal, they are offered the option to submit a request to the FIM CM server for a new set of certificates or a new permanent smart card. The request will end with the creation of either a software profile or a smart card profile.

Software profiles are created when you enroll for a software profile template or when you execute a duplicate, recover, renew, or recover on behalf request on an existing software profile. Smart card profiles are created when you enroll for a smart card profile template or when you duplicate, recover, renew, recover on behalf of an existing smart card.

The Provision API allows you to create a software profile or a smart card profile by executing an enroll request or a recover request. You can also search for existing profiles using this API. Once you have a profile or a smart card, you can look at what certificates the profile or smart card has.

For more information, see Understanding Profiles and Smart Cards.

Requests

FIM CM’s management and operational functions are based on requests. For example, any action that is performed within the FIM CM Web portal is based on a request. Requests are submitted and processed against a management policy, which is defined in the profile template.

When you create a request, and at some point execute the request, the behavior of the request execution is determined by the management policy. For example, if you create an enroll request and execute it, that behavior is defined by the enroll policy set on the profile template that you want to enroll for.

The request is stored in the FIM CM database and access rights are determined by checking the service connection point (for manager initiated requests), profile template settings, group permissions, and certificate template permissions. Within the FIM CM management policy, the security principals that are designated to initiate a request must be:

  • A user account

  • A global group

  • A universal group

Depending on the registration model and permissions assigned within the FIM CM environment, different security principals will execute requests. The requests can be executed by:

  • The FIM CM agent account

  • A designated enrollment agent

  • The certificate subscriber

  • A designated certificate manager (only for revoke, disable, suspend and reinstate requests where the certificate manager is the last approver of the request)

The FIM CM Provision API allows you to create, approve, deny, and execute the following requests: enroll, recover, unblock, offline unblock and retire. You can also use the Provision API to search for requests.

As the request is processed, the request will pass through different states. The actions that can be performed on a request are dependent on the current state of the request. For example, a request can only be executed when it is in an approved or executing state.

Request States

A request will be in one state as it enters the management policy operation, and exit in a different state. Request states can be set to none (only on error), approved, denied, pending, completed, failed, canceled, and executing. A request will change state as it progresses through the management policy workflow.

Using the FIM CM Provision API, you can get a particular request (identified by a GUID) and look at its request status. Request states change throughout the lifecycle of the request. A request will always begin in the pending state. Depending on the actions (approve, cancel, deny, etc.) taken on a request, it will change state. All request states are described below:

  • Pending - A request will be in a pending state after the initiation of the request if one or more approvals are required. If no approvals are required, the request can transition to an approved state.

  • Canceled - Once a request is in a pending state, the initiator of the request could choose to cancel the request. Also, it can only be canceled if the request has not yet been approved. Once canceled, the request will now be in a canceled state.

  • Denied - If an approver chooses to deny a pending request, the request will enter a denied state.

  • Approved - If all designated approvers choose to approve a pending request, or no approvers are designated, the request will enter an approved state.

  • Executing - When execution is initiated on an approved request, the request enters an executing state. A request also enters an executing state if it fails to execute due to permission problems or service failures.

  • Failed - A request gets to the failed state if and only if it is explicitly abandoned by a user with Request Execute permissions.

  • Completed - If an executing request successfully completes, the request enters a completed state.

Using the Provision API, you can modify the state of a request by calling operations like Approve, Deny, and Cancel. The state of a request is independent of the type of profile that the request is related to. Requests related to smart cards and software profiles go through the same lifecycle.

Software-based profile templates

Software profile templates allow you to enroll users for software certificates, which will be stored on the user's computer.

Software Profile Lifecycle

A software profile will pass through the following states during its lifecycle:

  • New - When a software profile is first introduced into the FIM CM environment, its status is set to New.

  • Active - A software profile enters an Active state when certificates are successfully installed for the software profile. The installation can take place during a duplicate, replace, or enroll process.

  • Suspended - A software profile will transition to a suspended state when a suspend operation takes place against the software profile. The software profile will return to an active state if the software profile is reinstated during a workflow.

  • Disabled - A software profile can transition to a disabled state from either an active state or a suspended state. A software profile will enter a disabled state if the software profile is explicitly revoked or as part of a replace or renewal action if the management policy is configured to disable existing software profiles.

Smart card-based profile templates

Smart card-based profile templates are processed similar to software-based profile templates. The major difference between the two types of profile templates is the policies defined for each profile template type. Smart card-based profile templates have policies like retire, unblock and offline unblock. Software-based profile templates do not have these policies. This implies that you can create and execute a retire request, unblock request or offline unblock request on a smart card, but not on a software profile.

You can create a smart card using the Provision API by calling the CreateSmartcard method. This will assign a smart card to a request and a particular user. The status of the smart card will be set to assigned.

Smart card Lifecycle

A smart card will pass through the following states during its lifecycle:

  • New - When a smart card is first introduced into the FIM CM environment, its status is set to new.

  • Assigned - A new smart card will transition to an assigned state when the smart card is assigned to a specific user. The assignment can take place by duplicating an existing smart card, replacing an existing smart card, or performing an initial enrollment of a smart card. When a smart card is assigned, it is tied to a specific user account in the FIM CM database, but certificates are not installed on the smart card.

  • Active - A smart card enters an active state when certificates are successfully installed on the smart card. The installation can take place during a duplicate, replace, or enroll process. A card will also enter an active state when a smart card is renewed, unblocked or offline unblocked.

  • Suspended - A smart card will transition to a suspended state when a suspend operation takes place against the smart card. The smart card will return to an active state if the smart card is reinstated during a workflow.

  • Disabled - A smart card can transition to a disabled state from either an active state or a suspended state. A smart card will enter a disabled state if the smart card is explicitly disabled or as part of a replace or renewal action if the management policy is configured to disable existing smart cards.

Request Workflows

When a request is submitted it is saved to the data store and its status is immediately set to Pending. As shown in the following illustration, developers can then perform various actions on a stored request once it has been submitted, which include approve, deny, cancel or execute requests. Depending on whether the action is accepted the status of each request is set to either approved, denied, canceled, executing, failed or completed.

Provision API Request Workflow

Permissions

The Provision API provides methods for validating a user's permissions on other users and FIM CM requests. In addition to the methods available in this class, you also may need to use Active Directory Service Interfaces (ADSI) available interfaces to verify permissions on profile templates, FIM CM service connection points, and certificate templates.

The Provision API also provides AccessCheck methods to perform the operations described above. For more information, see Permission Operations.

Remoting and In-Process Usage Model

Developers can call the Provision API in two ways:

Using .NET Remoting calls

.NET Remoting is a component provided by .NET that allows making calls to objects hosted in remote processes (for example, Remote Procedure Calls). Client applications can make remoting calls in order to make calls to remoted objects hosted in the IIS Process (w3wp.exe) where the FIM CM web application is running.

Using In-process calls

Developers can access the Provision API, or create notification handlers, or implement specific interfaces to run in-process with the FIM CM server. A developer could potentially write his/her own ASPX pages and make them run in the same process as the FIM CM Web application using the Provision API.

For more information, see FIM CM Remoting Configuration.