Skip to content

Commit 7f1ba7e

Browse files
mconnewmconnew
authored
Updating documentation for SecurityTokenProvider on .NET Core (#4017)
1 parent 8271f77 commit 7f1ba7e

File tree

1 file changed

+89
-28
lines changed

1 file changed

+89
-28
lines changed

‎xml/System.IdentityModel.Selectors/SecurityTokenProvider.xml

Lines changed: 89 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -428,11 +428,20 @@
428428
<Parameter Name="token" Type="System.IdentityModel.Tokens.SecurityToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.1;dotnet-plat-ext-5.0" />
429429
</Parameters>
430430
<Docs>
431-
<param name="timeout">To be added.</param>
432-
<param name="token">To be added.</param>
433-
<summary>To be added.</summary>
434-
<returns>To be added.</returns>
435-
<remarks>To be added.</remarks>
431+
<param name="timeout">A <see cref="T:System.TimeSpan" /> that specifies the timeout value for the message that cancels the security token.</param>
432+
<param name="token">The <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> to cancel.</param>
433+
<summary>Cancels a security token.</summary>
434+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous token cancellation operation.</returns>
435+
<remarks>
436+
<format type="text/markdown"><![CDATA[
437+
438+
## Remarks
439+
A security token that can be cancelled, such as one that is issued, allows a client that requested a security token to cancel it when it is done with it.
440+
441+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.CancelTokenAsync%2A> method calls <xref:System.IdentityModel.Selectors.SecurityTokenProvider.CancelTokenCoreAsync%2A> method.
442+
443+
]]></format>
444+
</remarks>
436445
</Docs>
437446
</Member>
438447
<Member MemberName="CancelTokenCore">
@@ -499,11 +508,22 @@
499508
<Parameter Name="token" Type="System.IdentityModel.Tokens.SecurityToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.1;dotnet-plat-ext-5.0" />
500509
</Parameters>
501510
<Docs>
502-
<param name="timeout">To be added.</param>
503-
<param name="token">To be added.</param>
504-
<summary>To be added.</summary>
505-
<returns>To be added.</returns>
506-
<remarks>To be added.</remarks>
511+
<param name="timeout">A <see cref="T:System.TimeSpan" /> that specifies the timeout value for the message that cancels the security token.</param>
512+
<param name="token">The <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> to cancel.</param>
513+
<summary>Cancels a security token.</summary>
514+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous token cancellation operation.</returns>
515+
<remarks>
516+
<format type="text/markdown"><![CDATA[
517+
518+
## Remarks
519+
A security token that can be cancelled, such as one that is issued, allows a client that requested a security token to cancel it when it is done with it.
520+
521+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.CancelTokenAsync%2A> method calls <xref:System.IdentityModel.Selectors.SecurityTokenProvider.CancelTokenCoreAsync%2A> method.
522+
523+
When the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.CancelTokenCoreAsync%2A> method is overridden and the security token passed into the token parameter cannot be canceled, throw the <xref:System.IdentityModel.Tokens.SecurityTokenException> exception.
524+
525+
]]></format>
526+
</remarks>
507527
</Docs>
508528
</Member>
509529
<Member MemberName="EndCancelToken">
@@ -807,10 +827,21 @@
807827
<Parameter Name="timeout" Type="System.TimeSpan" Index="0" FrameworkAlternate="dotnet-plat-ext-3.1;dotnet-plat-ext-5.0" />
808828
</Parameters>
809829
<Docs>
810-
<param name="timeout">To be added.</param>
811-
<summary>To be added.</summary>
812-
<returns>To be added.</returns>
813-
<remarks>To be added.</remarks>
830+
<param name="timeout">A <see cref="T:System.TimeSpan" /> that specifies the timeout value for the message that gets the security token.</param>
831+
<summary>Gets a security token.</summary>
832+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous read operation and wraps the <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> that represents the security token to get.</returns>
833+
<remarks>
834+
<format type="text/markdown"><![CDATA[
835+
836+
## Remarks
837+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenAsync%2A> method is called by the <xref:System.ServiceModel.Description.ClientCredentials> class when a client sends a SOAP message and a security token is required.
838+
839+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenAsync%2A> method calls the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenCoreAsync%2A> method.
840+
841+
In most cases the `timeout` parameter is not used by derived classes of <xref:System.IdentityModel.Selectors.SecurityTokenProvider> such as <xref:System.IdentityModel.Selectors.UserNameSecurityTokenProvider>. However, sometimes retrieving a security token involves distributed messaging. An example is <xref:System.ServiceModel.Security.Tokens.IssuedSecurityTokenProvider> used in a federated service. In these cases the `timeout` parameter is used to avoid exceptions caused by network failures, message loss, and other error conditions.
842+
843+
]]></format>
844+
</remarks>
814845
</Docs>
815846
</Member>
816847
<Member MemberName="GetTokenCore">
@@ -881,10 +912,20 @@
881912
<Parameter Name="timeout" Type="System.TimeSpan" Index="0" FrameworkAlternate="dotnet-plat-ext-3.1;dotnet-plat-ext-5.0" />
882913
</Parameters>
883914
<Docs>
884-
<param name="timeout">To be added.</param>
885-
<summary>To be added.</summary>
886-
<returns>To be added.</returns>
887-
<remarks>To be added.</remarks>
915+
<param name="timeout">A <see cref="T:System.TimeSpan" /> that specifies the timeout value for the message that gets the security token.</param>
916+
<summary>Gets a security token.</summary>
917+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous read operation and wraps the <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> that represents the security token to get.</returns>
918+
<remarks>
919+
<format type="text/markdown"><![CDATA[
920+
921+
## Remarks
922+
When the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenCoreAsync%2A> method is overridden and the security token passed into the token parameter cannot be obtained, throw the <xref:System.IdentityModel.Tokens.SecurityTokenException> exception.
923+
924+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenAsync%2A> method is called by the <xref:System.ServiceModel.Description.ClientCredentials> class when a client sends a SOAP message and a security token is required.
925+
926+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenAsync%2A> method calls the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.GetTokenCoreAsync%2A> method.
927+
]]></format>
928+
</remarks>
888929
</Docs>
889930
</Member>
890931
<Member MemberName="RenewToken">
@@ -957,11 +998,20 @@
957998
<Parameter Name="tokenToBeRenewed" Type="System.IdentityModel.Tokens.SecurityToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.1;dotnet-plat-ext-5.0" />
958999
</Parameters>
9591000
<Docs>
960-
<param name="timeout">To be added.</param>
961-
<param name="tokenToBeRenewed">To be added.</param>
962-
<summary>To be added.</summary>
963-
<returns>To be added.</returns>
964-
<remarks>To be added.</remarks>
1001+
<param name="timeout">A <see cref="T:System.TimeSpan" /> that specifies the timeout value for the message that renews the security token.</param>
1002+
<param name="tokenToBeRenewed">The <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> to renew.</param>
1003+
<summary>Renews a security token.</summary>
1004+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous read operation and wraps the <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> that represents the security token that is renewed.</returns>
1005+
<remarks>
1006+
<format type="text/markdown"><![CDATA[
1007+
1008+
## Remarks
1009+
An issued security token that is renewable allows a client to renew it when the security token is about to or has expired.
1010+
1011+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.RenewTokenAsync%2A> method calls the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.RenewTokenCoreAsync%2A> method.
1012+
1013+
]]></format>
1014+
</remarks>
9651015
</Docs>
9661016
</Member>
9671017
<Member MemberName="RenewTokenCore">
@@ -1036,11 +1086,22 @@
10361086
<Parameter Name="tokenToBeRenewed" Type="System.IdentityModel.Tokens.SecurityToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.1;dotnet-plat-ext-5.0" />
10371087
</Parameters>
10381088
<Docs>
1039-
<param name="timeout">To be added.</param>
1040-
<param name="tokenToBeRenewed">To be added.</param>
1041-
<summary>To be added.</summary>
1042-
<returns>To be added.</returns>
1043-
<remarks>To be added.</remarks>
1089+
<param name="timeout">A <see cref="T:System.TimeSpan" /> that specifies the timeout value for the message that renews the security token.</param>
1090+
<param name="tokenToBeRenewed">The <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> to renew.</param>
1091+
<summary>Renews a security token.</summary>
1092+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous read operation and wraps the <see cref="T:System.IdentityModel.Tokens.SecurityToken" /> that represents the security token that is renewed.</returns>
1093+
<remarks>
1094+
<format type="text/markdown"><![CDATA[
1095+
1096+
## Remarks
1097+
An issued security token that is renewable allows a client to renew it when the security token is about to or has expired.
1098+
1099+
When the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.RenewTokenCoreAsync%2A> method is overridden and the security token passed into the token parameter cannot be renewed, throw the <xref:System.IdentityModel.Tokens.SecurityTokenException> exception.
1100+
1101+
The <xref:System.IdentityModel.Selectors.SecurityTokenProvider.RenewTokenAsync%2A> method calls the <xref:System.IdentityModel.Selectors.SecurityTokenProvider.RenewTokenCoreAsync%2A> method.
1102+
1103+
]]></format>
1104+
</remarks>
10441105
</Docs>
10451106
</Member>
10461107
<Member MemberName="SupportsTokenCancellation">

0 commit comments

Comments
 (0)